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文档 声明 : 


© 根据 官方 最 新 的 1.1.2 版 本 做 了 翻译 
e Backbone.js (0.5.3) 文 档 请 移 步 http://www.css88.com/doc/backbone-0.5.3/; 
© 翻译 水 平 有 限 ， 如 果 您 有 任何 建议 ， 或 者 拍 砖 ， 欢 迎 在 微 博 上 @ 轧 人 码头 联系 我 。 


Backbone.js 为 复杂 WEB 应 用 程序 提供 模型 (models)、 集 合 (collections)、 视 图 (views) 的 结 
构 。 其 中 模型 用 于 绑 定 键 值 数据 和 自 定义 事件 ; 集合 附 有 可 枚 举 函 数 的 丰富 API ; 视图 可 以 声 
明 事 件 处 理 函 数 ， 并 通过 RESRful JSON 接 口 连接 到 应 用 程序 。 


此 项 目 托管 在 GitHub 上 , 并 且 提 供 带 注释 的 源码 , 在 线 的 测试 套件 , 应 用 示例 , 教程 列表 还 有 
一 个 实际 应 用 项 目的 超 长 列表 , 这 些 项 目 都 使 用 了 Backbone. Backbone 允许 在 MIT 软件 协 
议 下 使 用 . 


a issues 页 面 及 #documentcloud 频道 下 的 Freenode IRC} 报告 bug 和 讨论 功 
č, 在 Google Group 合 wiki 页 面 中 提出 问题 ， 或 在 twitter 上 @documentcloud ° 


Backbone% DocumentCloud 的 一 个 开源 组 件 . 


下 载 & 依 赖 (右键 另存 为 ) 


开发 版 本 (1.1.2) 60kb, 完整 的 源 代码 ， 大 量 的 注释 
ARAN (1.1.2) 6.5kb, 打包 和 gzip 压 缩 (Source Map) 
Edge Version (master) 未 发 布 版 本 ,使 用 风险 自负 


Backbone 唯 一 重度 依赖 的 是 Underscore.js( >= 1.5.0) ( 轧 人 码头 注 : Underscore.js 中 文 文档 
请 查看 http://www.css88.com/doc/underscore/) 。 基 于 RESTful (一 个 架构 样式 的 网 络 系 
统 ) 的 约束 ，histroy 的 支持 依赖 于 Backbone.Router ，DOM 处 理 依赖 于 Backbone.View， 包 
括 jQuery (>= 1.11.0), 和 json2.js 对 昌 的 IE 浏览 器 的 支持 。 (模仿 Underscore 和 jQuery 的 
APls， 例 如 上 Lo-Dash 和 Zepto， 在 不 同 的 兼容 性 下 也 一 样 能 运行 ) 


介绍 (Introduction ) 


当 我 们 开发 含有 大 量 Javascript 的 web 应 用 程序 时 ， 首 先 你 需要 做 的 事情 之 一 便 是 停止 向 DOM 
对 象 附 加 数据 。 通 过 复杂 多 变 的 jQuery 选择 符 和 回调 函数 很 容易 创建 Javascript 应 用 程序 ， 包 
括 在 HTML Ul，Javascript 逻 辑 和 数据 之 间 保 持 同步 ， 都 不 复杂 。 但 对 富 客 户 端 应 用 来 说 ， 良 
好 的 架构 通常 是 有 很 多 益处 的 。 


通过 Backbone， 你 可 以 将 数据 呈现 为 Models, 你 可 以 对 模型 进行 创建 ， 验 证 和 销毁 ， 以 及 将 
它 保存 到 服务 器 。 任 和 何 时 候 只 要 UI 事件 引起 模型 内 的 属性 变化 ， 模 型 会 触发 "change" 事 件 ; 
所 有 显示 模型 数据 的 Views 会 接收 到 该 事件 的 通知 ， 继 而 视图 重新 泻 染 。 你 无 需 查找 DOM 来 
搜索 指定 id 的 元 素 去 手动 更 新 HTML 。 一 当 模 型 改变 了 ， 视 图 便 会 自动 变化 。 


某 种 意义 上 说 ， 在 用 javaScript 来 创建 web 项 目 时 ，Backbone 试 图 定义 一 组 最 小 而 高 效 的 集 
合 ， 包 括 了 数据 结构 (models (模型 ) 和 collections (#4) ) 和 用 户 接口 (views ( 视 
图 ) 和 URLS) 。 在 web 开 发 环境 里 ， 到 处 都 是 框架 ( 帮 你 写 好 了 一 切 ) ， 不 过 这 些 库 需要 
你 的 网 站 在 构建 的 时 候 符合 该 框架 的 样子 ， 风 格 ， 默 认 的 行为 。 但 是 ，Backbone 还 是 作为 一 
个 工具 ， 让 你 可 以 随心 所 和 欲 的 设计 你 的 网 站 。 


如 果 你 不 懂 Backbone 或 者 不 确定 Backbone 能 否 帮 助 到 你 ， 先 运行 一 下 列表 中 基于 Backbone 
的 项 目 。 


文档 下 面 有 大 量 可 以 运行 的 例子 ， 请 点 击 play 执行 他 们 。 


升级 到 1.1 


从 Backbone 0.9.X 系 列 版 本 升级 到 1.1 应 该 是 相当 容易 的 。 如 果 你 从 旧版 本 升级 ， 一 定 要 检 
查 更 新 日 志 。 简 单 地 说 ， 一 些 大 规模 的 重大 更 改 是 : 


如 果 你 想 漂亮 的 更 新 一 个 Collection( 集 合 ) 的 内 容 ， 增 加 新 的 models (模型 ) > MRA 
失 ， 和 合并 那些 已 经 存在 ， 你 现在 可 以 调用 set( 以 前 叫做 "Update") > Model (模型 ) RM 
的 操作 也 调用 set 。 这 是 目前 默认 的 ， 当 你 在 collection (集合 ) 上 调用 fetch 时 。 为 了 得 
到 上 昌 的 行为 ， 传 递 {reset: true} ° 

如 果 你 的 URL 片 段 中 有 字符 ， 需 要 URL 编 码 ，Backbone 现 在 会 在 你 路 由 处 理 程序 接收 它 
们 作为 参数 前 为 你 解码 〈 跨 浏览 器 规范 的 行为 ) © 

在 0.9.x 中 ，Backbone 事件 有 了 两 个 新 的 方法 : listenTo 和 stopListening， 这 使 得 它 能 
更 容易 地 创建 Views (ALA) 监听 ， 当 你 想 remove view (视图 ) 时 ， 解 除 他 们 所 有 绑 定 
的 监听 。 

model (模型 ) 验证 现在 只 默认 执行 在 save 中 一 不 再 执行 在 set 中， 除非 传递 

了 {validate:true} 选项 。model (模型 ) 验证 现在 会 触发 一 个 "invalid" 事件 ， 而 不 
是 "error" 事件 

在 1.1 中 > Backbone Views (视图 ) 不 再 有 options 参数 自动 附加 在 this.options 上 。 
如 果 你 喜欢 可 以 继续 附加 。 

在 1.1 中 ，Collection 的 add ， remove , set , push , 40 shift 方法 现在 返回 来 自 
collection (集合 ) models (模型 ) (或 models)。 


Backbone.Events (事件 ) 


Events 是 一 个 可 以 融合 到 任何 对 象 的 模块 , BP 对 象 绑 定 和 触发 自 定义 事件 的 能 力 . Events 
在 绑 定 之 前 不 需要 声明 , 并 且 还 可 以 传递 参数 . 比如 : 


var object = {}; 


.extend(object, Backbone.Events); 


object.on("alert", function(msg) { 
alert("Triggered " + msg); 


3); 


object.trigger("alert", "an event"); 


举 个 例子 , 你 可 以 定义 一 个 事件 调度 程序 ， 然 后 在 你 应 用 的 不 同 地 方 调用 ， 例 如 


var dispatcher = _.clone(Backbone.Events) 


ON object.on(event, callback, [context]) 别名 : bind 在 object +2% < — ‘callback 7] 4 
数 。 只 要 event 触 发 ， 该 回调 函数 就 会 调用 。 如 果 你 的 一 个 页 KATS 的 不 同时 间 ， 我 们 约 
定 使 用 冒号 来 为 事件 添加 命 命名 空间 俗 成 地 使 用 冒号 来 命名 > "poll:start" , 或 
"change:selection" ° 事件 字符 囊 也 可 能 是 用 空格 分 隔 的 多 个 事件 列表 ( 思 人 码头 注 : 即 可 
以 同时 绑 定 多 个 事件 ， 事 件 用 空格 分 隔 ) … 


book.on("change:title change:author", ...); 
当 回 调 函 数 被 调用 时 ， 通 过 可 选 的 第 三 个 参数 可 以 为 this 提供 一 个 context (LF LX) 


值 : model. on('change', this.render, this) (BABKE: : 即 回调 函数 中 的 This ， 指 向 传递 
的 第 三 个 参数 ) 。 


当 回 调 函 数 被 绑 定 到 特殊 "all" 事 件 时 ， 任 何事 件 的 发 生 都 会 触发 该 回调 函数 ， 回 调 防 数 的 第 一 
个 参数 会 传递 该 事件 的 名 称 。 举 个 例子 ， 将 一 个 对 象 的 所 有 事件 代理 到 另 一 对 象 : 


proxy.on("all", function(eventName) { 
object.trigger(eventName); 


3); 


所 有 Backbone 事 件 方法 还 支持 事件 映射 的 语法 ， 作 为 可 惜 的 位 置 


book.on({ 
"change:title": titleView.update, 
"change:author": authorPane.update, 
"destroy": bookView. remove 


3); 


off object.off([event], [callback], [context]) 别名 : unbi nd 从 object 对 象 移 除 先前 绑 定 的 
callback 43 ° 47> RAAH context (LFX) ， 所 有 上 下 文 下 的 这 个 回调 函数 将 被 移 除 。 
如 果 没 有 指定 callback， 所 有 绑 定 这 个 事件 回调 函数 将 被 移 除 ; 如 果 没 有 指定 event， 所 有 事 

件 的 回调 函数 会 被 移 除 。 


// Removes just the “onChange callback. 
object.off("change", onChange); 


// Removes all "change" callbacks. 
object.off("change"); 


// Removes the ‘onChange callback for all events. 
object.off(null, onChange) ; 


// Removes all callbacks for ` context ” for all events. 
object.off(null, null, context); 


// Removes all callbacks on ‘object’. 
object.off(); 


需要 注意 的 是 ， 调 用 model.off() ， 例 如 ， 这 确实 会 删除 model (模型 ) 上 所 有 的 事件 一 包括 
Backbone 内 部 用 来 统计 的 事件 。 


trigger object.trigger(event, [*args]) fk Re event A ZK RAF AY SEY BI RR OG 
续 传 入 trigger 的 参数 会 传递 到 触发 事件 的 回调 函数 里 。 


once object.once(event, callback, [context]) 用 法 跟 on 很 像 ， 区 别 在 于 绑 定 的 回调 函数 能 
发 一 次 后 就 会 被 移 除 (BRAAK: 只 执行 一 次 ) 。 和 简单 的 说 就 是 “下 次 不 在 触发 了 ， 用 这 个 
FB ik” o 


listenTo object.listenTo(other, event, callback) 让 object 监听 4—~* (other) 对 象 上 的 
一 个 特定 事件 。 不 使 用 other.on(event, callback, object) ? 而 使 用 这 种 形 式 的 优点 

是 : listenTo 人 允许 object 来 跟踪 这 个 特定 事件 ， 并 且 以 后 可 以 一 次 性 全 部 移 除 它们 。callback 
总 是 在 object 上 下 文 环境 中 被 调用 。 


view.listenTo(model, 'change', view.render); 


stopListening object.stopListening([other]，[event]，[callback]) 让 object 停止 监听 事 
件 。 如 果 调 用 不 带 参 数 的 stopListening， 可 以 移 除 object 下 所 有 已 经 registered( 注 册 ) 的 
callback 元 数 ...， 或 者 只 删除 指定 对 象 上 明确 告知 的 监听 事件 ， 或 者 一 个 删除 指定 事件 ， 或 者 
只 删除 指定 的 回调 函数 。 


view.stopListening(); 


view.stopListening(model) ; 


listenToOnce object.listenToOnce(other, event, callback) 用 法 跟 listenTo 很 像 ， 但 是 事件 
触发 一 次 后 callback 将 被 移 除 。 


Catalog of Events (事件 目录 ) 下 面 是 Backbone 内 置 事件 的 完整 列表 ， 带 有 参数 。 你 也 可 
以 在 Models (模型 ) > Collection (#4) > Views (视图 ) 上 自由 地 触发 这 些 事件 ， 只 要 你 
认为 合适 。 收藏 和 意见 ， 你 认为 合适 。 Backbone 对 象 本 身 混 入 了 events ， 并 且 可 用 于 触发 
任何 全 局 事件 ， 只 要 您 的 应 用 程序 的 需要 。 


e "add" (model, collection, options) 一 当 一 个 model (模型 ) 被 添加 到 一 个 collection ( 集 
合 ) 时 触发 。 

e "remove" (model, collection, options) 一 当 一 个 model (模型 ) 从 一 个 collection ( 集 
合 ) 中 被 删除 时 触发 。 

e "reset" (collection, options) — 当 该 collection (集合 ) 的 全 部 内 容 已 被 蔡 换 时 触发 。 

e "sort" (collection, options) 一 当 该 collection (RA) 已 被 重新 排序 时 触发 。 

。 "change" (model, options) 一 当 一 个 model (模型 ) 的 属性 改变 时 触发 。 

。 "change:[attribute]" (model, value, options) 一 当 一 个 model (模型 ) 的 某 个 特定 属性 
被 更 新 时 触发 。 

e "destroy" (model, collection, options) — 当 一 个 model (模型 ) 被 destroyed (45%) 时 
触发 。 

e "request" (model_or_collection, xhr, options) — 当 一 个 model (模型 ) 或 collection ( 集 

合 ) 开始 发 送 请 求 到 服务 器 时 触发 。 
e "sync" (model_or_collection, resp, options) 一 当 一 个 model (模型 ) 或 collection ( 集 
合 ) 成 功 同步 到 服务 器 时 触发 。 

e "error" (model_or_collection, resp, options) 一 当 一 个 model (模型 ) 或 collection ( 集 
合 ) 的 请 求 远程 服 务 器 失败 时 触发 。 

e "invalid" (model, error, options) 一 当 model (模型 ) 在 客户 端 validation (验证 ) 失败 时 
触发 。 

e "route:[name]" (params) 一 当 一 个 特定 route (路 由 ) 相 匹 配 时 通过 路 由 器 触发 。 

e "route" (route, params) — 当 _ 任 何 一 个 _route (路 由 ) 相 匹 配 时 通过 路 由 器 触发 。 

e "route" (router, route, params) — 4 任何 一 个 _route (路 由 ) 相 匹配 时 通过 history (A 
史记 录 ) 触发 。 

。 "all" 一 所 有 事件 发 生 都 能 触发 这 个 特别 的 事件 ， 第 一 个 参数 是 触发 事件 的 名 称 。 


一 般 来 说 ， 事 件 触发 (例如 model.set，collection.add 或 者 其 他 事件 ) 后 就 会 执行 回调 函数 ， 
但 是 如 果 你 想 阻 止 回调 函数 的 执行 ， 你 可 以 传递 {silent: true} 作 为 参数 。 很 多 时 候 ， 这 是 一 个 
好 的 方法 。 通 过 在 回调 函数 里 传输 一 个 特定 的 判断 和 参数， 会 让 你 的 程序 更 加 出 色 。 一 般 而 
2? 事件 触发 ( model.set ， collection.add ,等 等 .. .) 后 就 会 调用 一 个 函数 ， 但 是 如 果 你 想 阻 
止 事件 被 触发 > 您 可 以 传递 {silent: true} 作为 一 个 选 先 项 。 注 意 ， 这 中 情 况 很 少 ， 甚至 从 来 
没有 ， 一 个 好 主意 。 通 过 在 选项 中 传递 一 个 特定 的 标记 ， 回 调 郊 数 里 传输 一 个 特定 的 判断 参 
数 并 且 选 择 忽 略 ， 会 让 你 的 程序 更 加 出 色 。 


Backbone.Model (模型 ) 


Models (模型 ) 是 任何 Javascript 应 用 的 核心 ， 包 括 数据 交互 及 与 其 相关 的 大 量 逻 辑 : 转 
换 、 验 证 、 计 算 属性 和 访问 控制 。 你 可 以 用 特定 的 方法 扩展 Backbone.Model，Model 也 提 
供 了 一 组 基本 的 管理 变化 的 功能 。 


下 面 的 示例 演示 了 如 何 定义 一 个 模型 ， 包 括 自 定义 方法 、 设 置 属性 、 以 及 触发 该 属性 变化 的 
事件 。 一 旦 运行 此 代码 后 sidebar 在 浏览 器 的 控制 台 就 可 用 ， 这 样 你 就 可 以 充分 发 挥 了 。 


var Sidebar = Backbone.Model.extend({ 
promptColor: function() { 
var cssColor = prompt("Please enter a CSS color:"); 
this.set({color: cssColor}); 


} 
3); 


window.sidebar = new Sidebar; 


sidebar.on('change:color', function(model, color) { 
$('#sidebar').css({background: color}); 


}); 
sidebar.set({color: 'white'}); 


sidebar.promptColor(); 


extend Backbone.Model.extend(properties, [classProperties]) 要 创建 自己 的 Model 类 ， 你 
可 以 扩展 Backbone.Model 并 提供 实例 properties( 属 性 ) ， 以 及 可 选 的 可 以 直接 注册 到 构造 
& áy classProperties(X %4 14) ° 

extend 可 以 正确 的 设置 原型 链 ， 因 此 通过 extend 创建 的 子 类 (subclasses) 也 可 以 被 深度 扩 
展 。 


var Note = Backbone.Model.extend({ 


initialize: function() { ... }, 
author: function() { ... }, 
coordinates: function() { ... }, 


allowedToEdit: function(account) { 
return true; 


} 
}); 
var PrivateNote = Note.extend({ 


allowedToEdit: function(account) { 
return account.owns(this); 


} 
3); 


父 类 ( super ) 的 简 述 : Javascript 没 有 提供 一 种 直接 调用 父 类 的 方式 一 如 果 你 要 重 载 原型 
链 中 上 层 定义 的 同名 函数 ， 如 set ,或 save ， 并 且 你 想 调 用 父 对 象 的 实现 ， 这 时 需要 明确 
的 调用 它 ， 类 似 这 样 : 


var Note = Backbone.Model.extend({ 
set: function(attributes, options) { 
Backbone.Model.prototype.set.apply(this, arguments); 


mee 
3); 


constructor / initialize new mModel([attributes], [options]) 当 创 建 model 实 例 时 ， 可 以 传 入 
属性 (attributes) 初 始 值 ， 这 些 值 会 被 set (设置 ) 到 modele 如 果 定 义 了 initialize HA > 
该 函数 会 在 model 创 建 后 执行 。 


new Book({ 
title: "One Thousand and One Nights", 
author: "Scheherazade" 


}); 


在 极 少 数 的 情况 下 ， 你 可 能 需要 去 重 写 constructor ， 它 可 以 让 你 替换 你 的 model 的 实际 构造 


var Library = Backbone.Model.extend({ 
constructor: function() { 
this.books = new Books(); 
Backbone.Model.apply(this, arguments); 
}, 
parse: function(data, options) { 
this.books.reset(data.books); 
return data. library; 
} 
}); 


如 果 你 传 入 {collection: ...} ， 这 个 options 表 示 这 个 model 属 于 哪个 collection ， 且 用 于 
计算 这 个 model 的 url。 否 则 model.collection 这 个 属性 会 在 你 第 一 次 添加 model 到 一 个 
collection 的 时 候 被 自动 添加 。 需要 注意 的 是 相反 的 是 不 正确 的 ， 因 为 传递 这 个 选项 给 构造 函 
数 将 不 会 自动 添加 model 到 集合 。 有 时 这 个 是 很 有 用 的 。 


如 果 {parse: true} 被 作为 一 个 option 选 项 传递 ，attributes 将 在 set 到 model 之 前 首先 通 
parse 被 转换 。 


get model.get(attribute) 从 当前 model 中 获取 当前 属性 (attributes) 值 ， 比 如 : 
note.get("title") 


set model.set(attributes, [options]) 向 model 设 置 一 个 或 多 个 hash 属 性 (attributes)。 如 果 任 
何 一 个 属性 改变 了 model 的 状态 ， 在 不 传 入 {Ssilent: true} 选项 参数 的 情况 下 ， 会 触发 
"change" 事件 ， 更 改 特 定 属性 的 事件 也 会 触发 。 可 以 绑 定 事件 到 某 个 属性 ， 例 


如 : change:title ’ 及 change:content ° 


note.set({title: "March 20", content: "In his eyes she eclipses..."}); 


book.set("title", "A Scandal in Bohemia"); 


escape model.escape(attribute) 与 get 类 似 ， 只 是 返回 的 是 HTML 转 义 后 版 本 的 model 属 性 
值 。 如 果 从 model 插 入 数据 到 HTML， 使 用 escape 取 数 据 可 以 避免 XSS 攻击 。 


var hacker = new Backbone.Model({ 
name: "<script>alert('xss')</script>" 


3); 


alert(hacker.escape('name')); 


has model.has(attribute) 属性 值 为 非 null 或 非 undefined 时 返回 true ° 


if (note.has("title")) { 


} 


unset model.unset(attribute, [options]) 从 内 部 属性 散 列 表 中 删除 指定 属性 (attribute)。 如 
果 未 设置 silent 选项 ， 会 触发 "change" 事件 。 


clear model.clear([options]) 从 model 中 删除 所 有 属性 ， 包 括 id 属性 。 如果 未 设置 
silent 选项 ， 会 触发 "change" 事件 。 


id model.id id 是 model 的 特殊 属性 ， 可 以 是 任意 字符 串 〈 整 型 id X UUD) 。 在 属性 中 设置 
的 id 会 被 直接 拷贝 到 model 属 性 上 。 我 们 可 以 从 集 含 〈collections) 中 通过 id 获取 model， 
另外 id 通常 用 于 生成 model 的 URLs 。 


idAttribute model.idattribute 一 个 model 的 唯一 标示 符 ， 被 储存 在 id 属性 下 。 如 果 使 用 一 
个 不 同 的 唯一 的 key 直 接 和 后 端 通信 。 可 以 设置 Model 的 idattribute 到 一 个 从 key 到 id 的 
一 个 透明 映射 中 。 


var Meal = Backbone.Model.extend({ 
idAttribute: "_id" 


}); 
var cake = new Meal({ _id: 1, name: "Cake" }); 
alert("Cake id: " + cake.id); 


cid model.cid model 的 特殊 属性 ，cid REP id 是 当 所 有 model 创 建 时 自动 产生 的 唯一 标识 
符 。 ZP ids 在 model 尚 未 保存 到 服务 器 之 前 便 存 在 ， 此 时 model 可 能 仍 不 具有 最 终 的 id ， 
但 已 经 需要 在 用 户 界面 可 见 。 


attributes model.attributes attributes 属性 是 包含 模型 状态 的 内 部 散 列 表 一 通常 (但 不 一 
Z) JSON 对 象 的 形式 表示 在 服务 器 上 模型 数据 。 它 通常 是 数据 库 中 一 个 行 的 简单 的 序列 ， 
但 它 也 可 以 是 客户 端的 计算 状态 。 


建议 采用 set 更 新 attributes 而 不 要 直接 修改 。 如果 您 想 检索 和 获取 模型 属性 的 副本 ， 用 
_.clone(model.attributes) 取而代之 。 


于 这 样 的 事实 : Events (事件 ) 接受 空格 分 隔 事件 列表 ， 但 是 属性 名 称 不 应 该 包括 空格 。 


changed model.changed changed 属 性 是 一 个 包含 所 有 属性 的 内 部 散 列 ， 自 最 后 set 已 改 
变 。 自 最 后 一 组 已 改变 。 请 不 要 直接 更 新 changed， 因 为 它 的 状态 是 由 Set 内 部 维护 。 


+ 但 


changed 的 副本 可 从 changedAttributes 获 得 。 


defaults model.defaults or model. deFaules() defaults #7] (XH) 用 于 为 模型 指定 默认 
属性 。 创建 模型 实例 时 ， 任 何 未 指定 的 属性 会 被 设置 为 其 默认 值 。 


var Meal = Backbone.Model.extend({ 


defaults: { 
"appetizer": "caesar salad", 
"entree": "ravioli", 
"dessert": "cheesecake" 
} 
}); 


alert("Dessert will be " + (new Meal).get('dessert')); 


需要 提醒 的 是 ， 在 Javascript 中 ， 对 象 是 按 引 用 传 值 的 ， 因 此 如 果 包 含 一 个 对 象 作为 默认 
值 ， 它 会 被 所 有 实例 共享 。 可 以 定义 defaults 为 一 个 函数 取代 。 


toJSON model.toJSON([options]) 返回 一 个 模型 的 attributes 浅 拷贝 副本 的 ISON 字符 串 化 
形式 。 它 可 用 于 模型 的 持久 化 、 序 列 化 ， 或 者 发 送 到 服务 之 前 的 扩充 。 该 方法 名 称 
乱 ， 因 为 它 事 实 上 并 不 返回 JSON 字符 串 ， 但 这 是 对 JavaScript API 的 JSON.stringify 实 
现 。 

var artist = new Backbone.Model({ 


firstName: "Wassily", 
lastName: "Kandinsky" 


3); 


artist.set({birthday: "December 16, 1866"}); 


alert(JSON.stringify(artist)); 


SYNC model.sync(method, model, [options]) 使 用 Backbone.sync 可 以 将 一 个 模型 的 状态 持 
续 发 送 到 服务 器 。 可 以 自 定 义 行为 覆盖 。 


fetch model.fetch([options]) 通过 委托 给 Backbone.sync 从 服务 器 重 置 模型 的 状态 。 返 回 
jqXHR。 如 果 模 型 从 未 填充 数据 时 非常 有 用 ， 或 者 如 果 你 想 确保 你 有 最 新 的 服务 器 状态 。 如 
果 服 务 器 的 状态 不 同 于 当前 属性 的 "change" 事件 将 被 触发 。 接 受 success 和 error 回调 的 
选项 散 列 ， 这 两 个 回调 都 可 以 传递 (model, response, options) 作为 参数 。 


// 每 隔 10 秒 从 服务 器 拉 取 数据 以 保持 频道 模型 是 最 新 的 
setInterval(function() { 

channel. fetch(); 
}, 10000); 


Save model.save([attributes], [options]) 通过 委托 给 Backbone.sync， 保 存 模型 到 数据 库 
(或 替代 持久 化 层 ) 。 如 果 验 证 成 功 ， 返 回 jqXHR， 和 否则 为 false © attributes#] (如 
set) 应 包含 你 想 改变 的 属性 - 不 涉及 的 键 不 会 被 修改 - 但 是 ， 该 资源 的 一 个 完整 表示 将 被 发 
送 到 服务 器 。 至 于 set ， 你 可 能 会 传递 单独 的 键 和 值 ， 而 不 是 一 个 哈 希 值 。 如 果 模 型 有 一 
个 validate 方 法 ， 并 且 验 证 失败 ， 该 模型 将 不 会 被 保存 。 如 果 模 型 isNew ， 保 存 将 采 

用 "create" (HTTP post ) ， 如 果 模 型 在 服务 器 上 已 经 存在 ， 保 存 将 采 

用 "update" (HTTP put ) ° 


相反 ， 如 果 你 只 想 将 改变 属性 发 送 到 服务 器 ， 调 用 model.save(attrs, {patch: true}) ° 你 会 
得 到 一 个 HTTP patch 请 求 将 刚刚 传 入 的 属性 发 送 到 服务 器 。 


通过 新 的 属性 调用 Save 将 立即 触发 一 个 "change" 事件 = 个 "request" 事件 作为 Ajax 请 求 
开始 到 服务 器 ， 并 且 当 服务 器 确认 成 功 修改 后 立即 触发 一 个 "sync" 事件 。 如 果 你 想 在 模型 
上 等 待 服务 器 设置 新 的 属性 ， 请 传递 {wait: true} 。 


在 下 面 的 例子 中 ， 注意 我 们 如 何 禾 盖 Backbone.sync 的 版 本 ， 在 模型 初次 保存 时 接收 到 
"create" 请 求 ， 第 二 次 接收 到 "update" 请 求 的 。 


Backbone.sync = function(method, model) { 
alert(method + ": " + JSON.stringify(model) ); 
model.set('id', 1); 

J; 


var book = new Backbone.Model({ 
title: "The Rough Riders", 
author: "Theodore Roosevelt" 


3); 
book.save(); 


book.save({author: "Teddy"}); 


save 支持 在 选项 散 列 表 中 传 入 success 和 error HW BHR? BARRA 
(model, response, options) 作为 参数 。 如 果 服 务 端 验 证 失败 ， 返 回 非 200 的 HTTP 响应 
码 ， 将 产生 文本 或 JSON 的 错误 内 容 。 


book.save("author", "F.D.R.", {error: function(){ ... }}); 


destroy model.destroy([options]) 通过 委托 给 Backbone.sync， 保 存 模型 到 数据 库 (或 替代 
持久 化 层 ) 。 通过 委托 一 个 HTTP pELETE 请 求 给 Backbone.sync 破 坏 服 务 器 上 的 模型 。 返回 
一 个 jqXHR 对 象 ， 或 者 如 果 模 型 jsSNew， 那 么 返回 false 。 选项 散 列 表 中 接受 success 和 
error 回调 函数 ， 回 调 函数 支持 传 入 (model, response, options) 作为 参数 。 在 模型 上 触 


发 "destroy" 事件 ， 该 事件 将 会 冒 泡 到 任何 包含 这 个 模型 的 集合 中 ， 一 个 "request" 事件 作 
为 Ajax 请 求 开 始 到 服务 器 ， 并 且 当 服务 器 确认 模型 被 删除 后 立即 触发 一 个 "sync" 事件 。 如 
果 你 想 在 集合 中 删除 这 个 模型 前 等 待 服务 器 相应 ， 请 传递 wait: true} ° 


book.destroy({success: function(model, response) { 


Ð; 


Underscore 方法 (6) Backbone 代理 了 Underscore.js 用 来 给 Backbone.Model 提 供 6 个 对 
象 函 数 。 这 里 没有 完全 记录 他 们 ， 但 你 可 以 看 看 Underscore 文 档 中 全 部 详情 ... (愚人 码头 注 : 
下 面 链接 已 经 替换 成 中 文 文 档 的 地 址 ) 


e keys 
e values 
e pairs 
e invert 
e pick 
e omit 


user.pick('first_name', 'last_name', 'email'); 


chapters.keys().join(', '); 


validate model.validate(attributes, options) 这 种 方法 是 未 定义 的 ， 如 果 您 有 任何 可 以 在 
JavaScript 中 执行 的 代码 并 且 我 们 鼓励 你 用 你 自 定义 验证 逻辑 履 盖 它 。 默认 情况 下 validate 
在 save 之 前 调用 ， 但 如 果 传 递 了 {validate:true} ， 也 可 以 在 set 之 前 调用 。 validate* 
法 是 通过 模型 的 属性 ， 选 项 和 set 和 save 是 一 样 的 。 如 果 属 性 是 有 效 的 ，validate 不 返 
回 验 证 任何 东西 ; 如 果 它 们 是 无 效 的 ， 返 回 一 个 你 选择 的 错误 。 它 可 以 是 一 个 用 来 显示 的 简 
单 的 字符 串 错误 信息 ， 或 一 个 以 编程 方式 描述 错误 的 完整 错误 对 象 。 如 果 validate 返 回 一 个 
BIR? save 不 会 继续 ， 并 且 在 服务 器 上 该 模型 的 属性 将 不 被 修改 。 校 验 失 败 将 触 

发 "invalid" 事件 ， 并 用 此 方法 返回 的 值 设 置 模型 上 的 validationError 属性 。 


var Chapter = Backbone.Model.extend({ 
validate: function(attrs, options) { 
if (attrs.end < attrs.start) { 
return "can't end before it starts"; 


}); 


var one = new Chapter({ 
title : "Chapter One: The Beginning" 


}); 
one.on("invalid", function(model, error) { 
alert(model.get("title") + " " + error); 
3); 
one.save({ 
start: 15, 
end: 10 
}); 


"invalid" 事件 提供 粗 粒 度 的 错误 信息 在 模型 或 集合 层面 上 是 很 有 用 。 
validationError model.validationError 用 validate 最 后 验证 失败 时 返回 的 值 。 


isValid model.isvalid() 运行 validate 来 检查 模型 状态 。 


var Chapter = Backbone.Model.extend({ 
validate: function(attrs, options) { 
if (attrs.end < attrs.start) { 
return "can't end before it starts"; 


H 


var one = new Chapter({ 
title : "Chapter One: The Beginning" 


}); 


one.set({ 
start: 15, 
end: 10 


3); 


if (!one.isValid()) { 
alert(one.get("title") + " " + one.validationError); 
} 


url model.url() 返回 模型 资源 在 服务 器 上 位 置 的 相对 URL 。 如 果 模 型 放 在 其 它 地 方 ， 可 通 
过 合理 的 逻辑 重 载 该 方法 。 URLs 的 默认 形式 为 : "/[collection.url]/[id]" > 如果 模 
型 不 是 集合 的 一 部 分 ， 你 可 以 通 定 明 确 的 urlRoot # a ° 


由 于 是 委托 到 Collection#url 来 生成 URL， 所 以 首先 需要 确认 它 是 否定 义 过 ， 或 者 所 有 模型 
共享 一 个 通用 根 URL 时 ， 是 否 存在 urlRoot 属性 。 例如， 一 个 id 为 101 的 模型 ， 存 储 在 
url Ä "/documents/7/notes" 4) Backbone.Collection 中 ， 那 么 该 模型 的 URL 


为 : “"/documents/7/notes/101" 


urlRoot model.urlRoot or model.urlRoot() 如 果 使 用 的 集合 外 部 的 模型 ， 通 过 指定 urlRoot 
来 设置 生成 基于 模型 id 的 URLs 的 默认 url 函数 。 "[urlRoot]/id" 。 通 常情 况 下 ， 你 不 会 
要 定义 这 一 点 。 需要 注意 的 是 urlRoot 也 可 以 是 一 个 函数 。 


var Book = Backbone.Model.extend({urlRoot : '/books'}); 
var solaris = new Book({id: "1083-lem-solaris"}); 


alert(solaris.url()); 


parse model.parse(response, options) parse 会 在 通过 fetch 从 服务 器 返回 模型 数据 ， 以 及 
save 时 执行 。 传 入 本 函数 的 为 原始 response 对 象 ， 并 且 应 当 返 回 可 以 set 到 模型 的 属性 散 
列表 。 默认 实现 是 自动 进行 的 ， 仅 简单 传 入 JSON 响应 。 如 果 需 要 使 用 已 存在 的 APL? RA 
更 好 的 命名 空间 响应 ， 可 以 重 载 它 


如 果 使 用 的 3.1 版 本 之 前 的 Rails 后 端 ， is Rails's 默认 的 to_json 实现 已 经 包含 了 命 
名 空间 之 下 的 模型 属性 。 对 于 无 缝 的 后 端 集成 环境 禁用 这 种 行为 : 


ActiveRecord: :Base.include_root_in_json = false 


clone model.clone() 返回 该 模型 的 具有 相同 属性 的 新 实例 。 
isNew model.isNew() 模型 是 否 已 经 保存 到 服务 器 。 如 果 模 型 尚 无 id ， 则 被 视 为 新 的 。 


hasChanged model. op 标识 模型 从 上 次 set 事件 发 生 后 是 否 改 变 过 。 
如 果 传 入 attribute ， 当 指定 属性 改变 后 返回 true 。 


注意 ， 本 方法 以 及 接 下 来 change 相关 的 方法 ， 仅 对 "change" 事件 发 生 有 效 。 


book.on("change", function() { 
if (book.hasChanged("title")) { 


Ta 
3); 


changedAttributes model.changedAttributes([attributes]) 只 从 最 后 一 次 set 开 始 检 索 已 改 
变 的 模型 属性 散 列 (hash) ， 或 者 如 果 没 有 ， 返 回 false 。 作为 可 选 ， 可 以 传递 外 部 属性 
ed (hash) ， 返 回 与 该 模型 不 同 的 属性 的 哈 希 (hash) 。 这 可 以 用 来 找 出 视图 的 哪些 部 分 
应 该 更 新 ， 或 者 确定 哪些 需要 与 服务 器 进行 同步 。 


previous model.previous(attribute) 在 "change" 事件 发 生 的 过 tHE > 本 方法 可 被 用 于 获取 
已 改变 属性 的 旧 值 。 


var bill = new Backbone.Model({ 
name: "Bill Smith" 


3); 


bill.on("change:name", function(model, name) { 
alert("Changed name from " + bill.previous("name") + " to " + name); 


3); 


bill.set({name : "Bill Jones"}); 


previousAttributes model.previousAttributes() 返回 模型 的 上 一 个 属性 的 副本 。 一 般 用 于 获 
取 模 型 的 不 同 版 本 之 间 的 区 别 ， 或 者 当 发 生 错误 时 回 滚 模型 状态 。 


Backbone.Collection ( 44 ) 


集合 是 模型 的 有 序 组 合 ， 我 们 可 以 在 集合 上 绑 定 "change" 事件 ， 从 而 当 集 合 中 的 模型 发 生 
变化 时 fetch (获得 ) 通知 ， 集 合 也 可 以 监听 "ada" 和 "remove" 事件 ， 从 服务 器 更 新 ， 
并 能 使 用 Underscore.js 提供 的 方法 。 


集合 中 的 模型 触发 的 任何 事件 都 可 以 在 集合 身上 直接 触发 ， 所 以 我 们 可 以 监听 集合 中 模型 的 


变化 : documents.on("change:selected", ...) 


extend Backbone.Collection.extend(properties, [classProperties]) 通过 扩展 
Backbone.Collection 创建 一 个 Collection 类 。 实 例 属性 参数 properties 以 及 类 属性 参数 
classProperties 会 被 直接 注册 到 集合 的 构造 函数 。 


model collection.model 履 盖 此 属性 来 指定 集合 中 包含 的 模型 类 。 可 以 传 入 原始 属性 对 象 
(和 数组 ) 来 add, create, 和 reset， 传 入 的 属性 会 被 自动 转换 为 适合 的 模型 类 型 。 


var Library = Backbone.Collection.extend({ 
model: Book 


3); 


H 
| 
? 
ies 


集合 也 可 以 包含 多 态 模型 ， 通 过 用 构造 函数 重 写 这 个 属性 ， 返 


var Library = Backbone.Collection.extend({ 


model: function(attrs, options) { 
if (condition) { 
return new PublicDocument(attrs, options); 
} else { 
return new PrivateDocument(attrs, options); 


3); 


constructor / initialize new Backbone.collection([models], [options]) 当 创 建 集合 时 ， 你 可 
以 选择 传 入 初始 的 models 数组 。 集合 的 comparator 函数 也 可 以 作为 选项 传 入 。 1% 

递 false 作为 comparator 选 项 将 阻止 排序 。 如果 定义 了 initialize 函数 ， 会 在 集合 创建 时 被 
调用 。 有 几 个 选项 ， 如 果 提 供 的 话 ， 将 直接 附加 到 集合 上 : model 和 comparator ° 通过 传 
递 null 给 models 选项 来 创建 一 个 空 的 集合 。 


var tabs = new TabSet([tab1, tab2, tab3]); 
var spaces = new Backbone.Collection([], { 
model: Space 


3); 


models collection.models 访问 集合 中 模型 的 内 置 的 JavaScript 数组 。 通 常 我 们 使 用 get ， 
at ， 或 Underscore 方 法 访问 模型 对 象 ， 但 偶尔 也 需要 直接 访问 。 


toJSON collection.toJSON([options]) 返回 集合 中 包含 的 每 个 模型 (通过 toJSON) 的 属性 哈 
希 的 数组 。 可 用 于 集合 的 序列 化 和 持久 化 。 本 方法 名 称 容易 引起 混淆 ， 因 为 它 与 JavaScript's 
JSON API 命名 相同 。 


var collection = new Backbone.Collection([ 
{name: "Tim", age: 5}, 
{name: "Ida", age: 26}, 
{name: "Rob", age: 55} 

]); 


alert(JSON.stringify(collection) ); 


sync collection.sync(method, collection, [options]) 使 用 Backbone.sync 来 将 一 个 集合 的 
状态 持久 化 到 服务 器 。 可 以 自 定 义 行为 必 盖 。 


Underscore 方法 (32) Backbone 代理 了 Underscore.js 用 来 给 Backbone.Collection 提 供 6 
个 对 得 函数 。 这 里 没有 完全 记录 他 们 ， 但 你 可 以 看 看 Underscore 文 档 中 全 部 详情 ...( 轴 人 码头 
注 : 下 面 链接 已 经 替换 成 中 文 文档 的 地 址 ) 


e forEach (each) 

e map (collect) 

e reduce (foldl, inject) 
e reduceRight (foldr) 
e find (detect) 

e filter (select) 

e reject 

e every (all) 

e some (any) 

e contains (include) 
e invoke 

e max 

e min 

e sortBy 

e groupBy 

e shuffle 

e toArray 

e size 

e first (head, take) 
e initial 

e rest (tail, drop) 

e last 

e without 

e indexOf 

e lastIndexOf 


e isEmpty 
e chain 

e difference 
e sample 
e partition 
e countBy 
e indexBy 


books.each(function(book) { 
book. publish(); 
3); 


var titles = books.map(function(book) { 
return book.get("title"); 


3); 

var publishedBooks = books.filter(function(book) { 
return book.get("published") === true; 

3); 


var alphabetical = books.sortBy(function(book) { 
return book.author.get("name").toLowerCase(); 


3); 


add collection.add(models, [options]) 向 集合 中 增加 一 个 模型 (或 一 个 模型 数组 ) > AR 

发 "add" Sto 如果 已 经 定义 了 model 属 性 ， 您 也 可 以 通过 原始 属性 的 对 象 让 其 看 起 来 像 一 
个 模型 实例 。 返回 已 经 添加 的 〈 或 预先 存在 的 ， 如 果 重 复 ) 模式 。 传递 fat: index} 可 以 将 
模型 插入 集合 中 特定 的 index 索引 位 置 。 如 果 您 要 添加 集合 中 已 经 存在 的 模型 到 集合 ， 他 
们 会 被 忽略 ， 除 非 你 传递 (merge: true} ， 在 这 种 情况 下 ， 它 们 的 属性 将 被 合并 到 相应 的 模 
型 中 ， 触 发 任何 适当 的 "change" 事件 。 


var ships = new Backbone.Collection; 


ships.on("add", function(ship) { 
alert("Ahoy " + ship.get("name") + "!"); 
}); 


ships.add([ 
{name: "Flying Dutchman"}, 
{name: "Black Pearl"} 

]); 


请 注意 ， 添 加 相同 的 模型 (具有 相同 id 的 模型 ) 到 一 个 集合 ， 一 次 以 上 是 空 操作 。 


remove collection.remove(models，[options]) 从 集合 中 删除 一 个 模型 (或 一 型 数组 ) ， 
并 且 返 回 他 们 。 会 触发 "remove" 事件 ， 同 样 可 以 使 用 silent 关闭 。 aes 该 术 ie 
可 用 作 options.index 类 监听 。 


reset collection.reset([models], [options]) 每 次 都 是 只 添加 和 删除 一 个 模型 那 没 问题 ， 但 
有 时 ， 你 需要 改变 很 多 模型 ， 那 么 你 宁愿 只 更 新 集合 。 使 用 reset， 将 一 个 新 的 模型 (或 属性 
散 列 ) 列表 替换 集合 ， 最 后 触发 一 个 但 单独 的 "reset" 事件 。 到 与 模型 的 新 列表 替换 集合 


(或 属性 散 列 ) ， 触 发 一 个 单一 的 “复位 "事件 在 末端 返回 新 的 模型 集合 。 为 方便 起 见 ， 在 
一 个 "reset" 事件 中 ， 任 何以 前 的 模型 列表 可 作为 options.previousModels ° 通过 传 
递 null 给 models 选项 来 清空 你 的 集合 。 


下 面 是 一 个 例子 使 用 reset 来 引导 一 个 集合 在 页 面 初始 化 时 加 载 ， 在 Rails 应 用 程序 中 : 


<script> 
var accounts = new Backbone.Collection; 
accounts.reset(<%= @accounts.to_json %>); 
</script> 


调用 collection.reset() ， 不 传递 任何 模型 作为 参数 将 清空 整个 集合 8 


set collection.set(models, [options]) Set 方 法 通过 传递 模型 列表 执行 一 个 集合 的 "smart( 智 
能 )" 的 更 新 。 如 果 列 表 中 的 一 个 模型 尚 不 在 集合 中 ， 那 么 它 将 被 添加 ; 如 果 模 型 已 经 在 集合 
中 ， 其 属性 将 被 合并 ; 并 且 如 果 集 合 包 含 不 存在 于 列表 中 的 任何 模型 ， 他 们 将 被 删除 。 以 上 所 
有 将 触发 相应 的 "add" , "remove" ， 和 和 "change" 事件 > 返回 集合 中 的 模型 。 如果 您 想 自 定 
义 的 行为 ， 你 可 以 设置 选项 : {add: false} , {remove: false} ,或 {merge: false} ， 将 其 禁 

用 。 


var vanHalen = new Backbone.Collection([eddie, alex, stone, roth]); 
vanHalen.set([eddie, alex, stone, hagar]); 


// Fires a "remove" event for roth, and an "add" event for "hagar". 
// Updates any of stone, alex, and eddie's attributes that may have 
// changed over the years. 


get collection.get(id) 通过 一 个 id， 一 个 cid， 或 者 传递 一 个 model 来 获得 集合 中 的 模型 。 
var book = library.get(110); 

at collection.at(index) 获得 集合 中 指定 索引 的 模型 。 不 论 你 是 否 对 模型 进行 了 重新 排序 ， 

at 始终 返回 其 在 集合 中 插入 时 的 索引 值 。 

push collection.push(model, [options]) 在 集合 尾部 添加 一 个 模型 。 选 项 和 add 相 同 。 

POP collection.pop([options]) 删除 并 且 返 回 集合 中 最 后 一 个 模型 。 选 项 和 remove 相 同 。 


unshift collection.unshift(model, [options]) 在 集合 开始 的 地 方 添加 一 个 模型 。 选 项 和 add 
相同 。 


shift collection.shift([options]) 删除 并 且 返 回 集合 中 第 一 个 模型 。 选 项 和 remove 相 同 。 


slice collection.slice(begin, end) 返回 一 个 集合 的 模型 的 浅 找 贝 副本 ， 使 用 与 原 
生 Array#slice 相 同 的 选项 。 


length collection.length 与 数组 类 似 ， 集 合 拥有 length 属性 ， 返 回 该 集合 包含 的 模型 数 


a 
o 


里 


comparator collection.comparator 默认 情况 下 ， 集 合 没有 声明 comparator HA ° wR E 
义 了 该 函数 ， 集 合 中 的 模型 会 按照 指定 的 站 法 进行 排序 。 换言之 ， 被 增加 模型 ， 会 被 插入 
collection.models 中 适合 的 位 置 。comparator 可 以 被 定义 为 sortBy〈 传 递 带 有 一 个 参数 的 函 
数 ) ， 作 为 一 个 sort (传递 一 个 一 个 参数 函数 需要 两 个 参数 ) ， 或 者 作为 一 个 表示 属性 的 字 
符 串 进行 排序 。 


"sortBy" 比 较 函 数 接受 一 个 模型 ， 并 且 返 回 一 个 该 模型 相对 于 其 他 模型 的 排序 数字 或 字符 串 
值 。"sort" 比 较 函 数 接受 两 个 模型 ， 并 且 ， 如 果 第 一 个 模型 应 该 在 第 二 模型 个 之 前 ， 返 

E -1 ; 如 果 他 们 是 同一 等 级 的 ， 返 回 @ ; 如 果 第 一 个 模型 应 该 在 第 二 模型 个 之 后 ， 返 

回 1 ; 需要 注意 的 是 Backbone 这 两 种 风格 的 比较 功能 的 确定 取决 于 参数 个 数 。 所 以 如 果 你 
绑 定 了 比较 函数 ， 需 要 格外 小 心 。 


注意 即使 下 面 例子 中 的 chapters 是 后 加 入 到 集合 中 的 ， 但 它们 都 会 遵循 正确 的 排序 : 


var Chapter 
var chapters 


Backbone.Model; 
new Backbone.Collection; 


chapters.comparator = 'page'; 


chapters.add(new Chapter({page: 9, title: "The End"})); 
chapters.add(new Chapter({page: 5, title: "The Middle"})); 
chapters.add(new Chapter({page: 1, title: "The Beginning"})); 


alert(chapters.pluck('title')); 


to RVG BREA BE > AA LR HRI RS RSA ASHE o 所 以 你 不 妨 改 变 模型 的 属 
性 后 调用 sort ， 这 会 影响 排序 。 


sort collection.sort([options]) 强制 对 集合 进行 重 排序 。 一 般 情 况 下 不 需要 调用 本 函数 ， 
A 4 — AAA RA > comparator 函数 会 实时 排序 。 要 禁用 添加 模型 时 的 排序 ， 可 以 传 
递 {sort: false} 给 add 。 调用 sort 会 触发 的 集合 的 "sort" 事件 9 


pluck collection.pluck(attribute) 从 集合 中 的 每 个 模型 中 拉 取 attribute (属性 ) 。 等 价 于 调 
用 map ， 并 从 和 迭代 器 中 返回 单个 属性 。 


var stooges = new Backbone.Collection([ 
{name: "Curly"}, 
{name: "Larry"}, 
{name: "Moe"} 


]); 
var names = stooges.pluck("name"); 


alert(JSON.stringify(names) ); 


where collection.where(attributes) 返回 集合 中 所 有 匹配 所 传递 attributes (属性 ) 的 模型 
数组 。 对 于 简单 的 filter (tie) 比较 有 用 。 


var friends = new Backbone.Collection([ 


{name: "Athos", job: "Musketeer"}, 
{name: "Porthos", job: "Musketeer"}, 
{name: "Aramis", job: "Musketeer"}, 


{name: "d'Artagnan", job: "Guard"}, 


]); 
var musketeers = friends.where({job: "Musketeer"}); 


alert(musketeers.length); 


findWhere collection.findwhere(attributes) 就 像 where， 不 同 的 是 findWhere 直 接 返 回 匹 
OPT 2% attributes (属性 ) 的 第 一 个 模型 。 


url collection.url or collection.url() 设置 url 属性 (或 函数 ) 以 指定 集合 对 应 的 服务 器 位 
置 。 集 合 内 的 模型 使 用 url 构造 自身 的 URLs 。 


var Notes = Backbone.Collection.extend({ 
url: '/notes' 


}); 
// Or, something more sophisticated: 


var Notes = Backbone.Collection.extend({ 
url: function() { 
return this.document.url() + '/notes' 
} 
}); 


parse collection.parse(response, options) 每 一 次 调用 fetch 从 服务 器 拉 取 集合 的 模型 数据 
时 ，parse 都 会 被 调用 。 本 函数 接收 原始 response 对 象 ， 返 回 可 以 added (添加 ) 到 集合 
的 模型 属性 数组 。 默 认 实 现 是 无 需 操作 的 ， 只 需 简单 传 入 服务 端 返回 的 JSON 对 象 。 如 果 需 
要 处 理 遗 留 API， 或 者 在 返回 数据 定义 自己 的 命名 空间 ， 可 以 重 写 本 有 函数 。 


var Tweets = Backbone.Collection.extend({ 
// The Twitter Search API returns tweets under "results". 
parse: function(response) { 
return response.results; 


} 
3); 


clone collection.clone() 返回 一 个 模型 列表 完全 相 同 的 集合 新 实例 2 


fetch collection.fetch([options]) 从 服务 器 拉 取 集合 的 默认 模型 设置 ， 成 功 接收 数据 后 会 
setting (设置 ) 集合 。 options 支持 success 和 error 回调 函数 ， 两 个 回调 函数 接收 
(collection, response, options) 作为 参数 。 当 模型 数据 从 服务 器 返回 时 ， 它 使 用 set 来 (F 
能 的 ) 合并 所 获取 到 的 模型 ， 除 非 你 传递 了 {reset: true} ， 在 这 种 情况 下 2 集合 将 (有 效 
地 ) 重 置 。 可 以 委托 Backbone.sync 在 幕后 自 定义 持久 性 策略 并 返回 一 个 jdqXHR。 fetch 请 
求 的 服务 器 处 理 器 应 该 返回 模型 JSON 数 组 。 


Backbone.sync = function(method, model) { 
alert(method + ": " + model.url); 


}; 


var accounts 
accounts.url 


new Backbone.Collection; 
'/accounts'; 


accounts.fetch(); 


fetch 行 为 可 以 通过 使 用 有 效 的 set 选 项 进行 定制 。 例 如， 要 获取 一 个 集合 ， 每 一 个 新 的 模型 
会 得 到 一 个 "ada" 事件 ， 和 每 改变 现 有 的 模型 的 "change" 事件 ， 不 删除 任何 东西 : 


collection.fetch({remove: false}) 


jQuery.ajax 选 项 也 可 以 直接 传递 作为 fetch 选 项 ， 所 以 要 获取 一 个 分 页 集合 的 特定 页 面 使 
用 : Documents.fetch({data: {page: 3}}) ° 


需要 注意 的 是 fetch 不 应 该 被 用 来 在 页 面 加 载 完 毕 时 填充 集合 数据 一 所 有 页 面 初始 数据 应 当 
在 bootstrapped 时 已 经 就 绪 。 fetch 适用 于 惰性 加 载 不 需 立 刻 展现 的 模型 数据 : 例如 : 例如 
文档 中 可 切换 打开 和 关闭 的 选项 卡 内 容 。 


create collection.create(attributes, [options]) 方便 的 在 集合 中 创 | 建 一 个 模型 的 新 实例 9 
相当 于 使 用 属性 哈 硕 ee 实例 化 一 个 模型 ， 然 后 将 该 模型 保存 到 服务 器 ， 创 建成 功 
后 将 模型 添加 到 集合 中 。 返回 这 个 新 模型 。 如 果 客 户 端 验证 失败 ， 该 模型 将 不 会 被 保存 ， 与 
验证 错误 。 为 了 能 正常 运行 ， 需 要 在 集合 中 设置 model 属性 。 create 方法 接收 键 值 对 象 或 者 
已 经 存在 尚未 保存 的 模型 对 象 作为 参数 。 


创建 一 个 模型 将 立即 触发 集合 上 的 "add" 事件 ， 一 个 "request" 的 事件 作为 新 的 模型 被 发 送 
到 服务 器 ， Rots. "sync" ?事件 ， 一 旦 服务 器 响应 成 功 创建 模型 。 如 果 你 想 在 集合 中 添 


加 这 个 模型 前 等 待 服务 器 相应 ， 请 传递 {wait: true} ° 
var Library = Backbone.Collection.extend({ 
model: Book 
3); 


var nypl = new Library; 


var othello = nypl.create({ 
title: "Othello", 
author: "William Shakespeare" 


}); 


Backbone.Router (路 由 ) 


用 程序 通常 需要 为 应 用 的 重要 位 置 提供 可 链接 ， 可 收藏 ， 可 分 享 的 URLs。 直到 最 近 ， 

fo. (hash) 片段 ( #page ) 可 以 被 用 来 提供 这 种 链接 ， 同 时 随 着 History API 的 到 来 ， 猫 
J URLs ( /page ) 。 Backbone.Router 为 客户 端 路 由 提供 了 许多 
方法 ， 并 能 连接 到 指定 的 动作 (actions) 和 事件 (events) 。 对 于 不 支持 History API 的 昌 
浏览 器 ， 路 由 提供 了 优雅 的 回调 函数 并 可 以 透明 的 进行 URL 片段 的 转换 。 


页 面 加 载 期 间 ， 当 应 用 已 经 创建 了 所 有 的 路 由 ， 需 要 调用 Backbone.history.start() ， 或 
Backbone.history.start({pushState: true}) 来 确保 驱动 初始 化 URL 的 路 由 。 


ri Backbone .Router .extend(properties, [esere PORRETTA 开始 创 1 建 一 个 自 定 义 的 路 由 
。 当 匹配 了 URL 片段 便 执 行 定义 的 动作 ， 并 可 以 通过 routes 定义 路 由 动作 键 值 对 。 请 注 
a 你 要 避免 在 路 由 定义 时 使 用 前 导 斜 杠 : 


var Workspace = Backbone.Router.extend({ 


routes: { 
"help": "help", // #help 
"search/: query": "search", // #search/kiwis 
"search/:query/p:page": "search" // #search/kiwis/p7 

}, 

help: function() { 

}, 

search: function(query, page) { 

} 

}); 


routes router.routes routes 将 带 参 数 的 URLs 映射 到 路 由 实例 的 方法 上 (或 只 是 直接 的 函 
数 定义 ， 如 果 你 喜欢 ) ， 这 与 View (视图 ) 的 events hash (事件 键 值 对 ) 非常 类 似 。 路 由 
可 以 包含 参数 ， param > CERA N EA URL 组 件 。 路 由 也 支持 通配符 ， *splat ， 可 
以 匹配 多 个 URL 组 件 。 路 由 的 可 选 部 分 放 在 括号 中 (/:optional) ° 


举 个 例子 ， 路 由 "search/: query/p: page" 能 匹配 #search/obama/p2 ,这 里 传 入 了 "obama" 和 
non 到 路 由 对 应 的 动作 中 去 了 。 


路 由 "file/*path" 可 以 匹配 #file/nested/folder/file.txt ， 这 时 传 入 动作 的 参数 为 


"nested/folder/file.txt" ° 


路 由 "docs/:section(/:subsection)" 可 以 匹配 #docs/faq 和 #docs/faq/installing ， 第 一 种 
情况 ， 传 入 "faq" 到 路 由 对 应 的 动作 中 去 ， 第 二 种 情况 ， 传 入 "Faq" 和 "installing" 到 
路 由 对 应 的 动作 中 去 。 


结尾 的 斜 杠 会 被 当 作 URL 的 一 部 分 ， 访 问 时 会 被 (正确 地 ) 当 作 一 个 独立 的 路 由 。 docs 和 
docs/ 将 触发 不 同 的 回调 。 如 果 你 不 能 避免 产生 这 两 种 类 型 的 URLs 时 ， 你 可 以 定义 一 
个 "docs(/)" 来 匹配 捕 提 这 两 种 情况 。 


当 访问 者 点 击 浏览 器 后 退 按钮 ， 或 者 输入 URL ， 如 果 匹 配 一 个 路 由 ， 此 时 会 触发 一 个 基于 动 
作 名 称 的 event， 其 它 对 象 可 以 监听 这 个 路 由 并 接收 到 通知 。 下 面 的 示例 中 ， 用 户 访问 
#help/uploading 将 从 路 由 中 触发 route:help 事件 2 


routes: { 
"help/:page": "help", 
"download/*path": "download", 
"folder/:name": "openFolder", 
"folder/:name-:mode": "openFolder" 
} 


router.on("route:help", function(page) { 


D 


constructor / initialize new Router([options]) 当 创 建 一 个 新 路 由 是 ， 你 可 以 直接 传 入 
routes 键 值 对 象 作为 参数 。 如 果 定 义 该 参数 ， 它 们 将 被 传 入 initialize 构造 函数 中 初始 
化 。 


route router.route(route, name, [callback]) 为 路 由 对 象 手 动 创 建 路 由 ， route 参数 可 以 是 
routing string (路 由 字符 囊 ) 或 正则 表达 式 。 每 个 捕 提 到 的 被 传 入 的 路 由 或 正则 表达 式 ， 都 
将 作为 参数 传 入 回调 函数 (callback) 。 一 旦 路 由 匹配 ， name 参数 会 触发 "route:namen 
事件 。 如 果 callback 参数 省 略 router [name] 将 被 用 来 代替 外 后 来 添加 的 路 由 可 以 覆盖 先前 
声明 的 路 由 。 


initialize: function(options) { 


// Matches #page/10, passing "10" 
this.route("page/:number", "page", function(number){ ... }); 


// Matches /117-a/b/c/open, passing "117-a/b/c" to this.open 
this. route(/4(.*?)\/open$/, "open"); 


}, 


open: function(id) { ... } 


navigate router.navigate(fragment, [options]) 每 当 你 达到 你 的 应 用 的 一 个 点 时 ， 你 想 保 存 
为 一 个 URL ， 可 以 调用 navigate 以 更 新 的 URL。 如 果 您 也 想 调 用 路 由 功能 ， 设 置 trigger 选 
项 设置 为 true 。 无需 在 浏览 器 的 历史 记录 创建 条 目 来 更 新 URL ， 设 置 replace 选 项 设置 

为 true 。 


openPage: function(pageNumber) { 
this.document.pages.at(pageNumber ).open(); 
this.navigate("page/" + pageNumber); 


} 


# Or... 
app.navigate("help/troubleshooting", {trigger: true}); 
# Or... 


app.navigate("help/troubleshooting", {trigger: true, replace: true}); 


execute router.execute(callback, args) 这 种 方法 在 路 由 内 部 被 调用 ， 每 当 路 由 和 其 相应 的 
callback 匹 配 时 被 执行 。 禾 盖 它 来 执行 自 定义 解析 或 包装 路 由 ， 例 如 ， 在 传递 他 们 给 你 的 路 
由 回调 之 前 解析 查询 字符 串 ， 像 这 样 : 


var Router = Backbone.Router.extend({ 
execute: function(callback, args) { 
args.push(parseQueryString(args.pop())); 
if (callback) callback.apply(this, args); 
} 
3); 


Backbone.history 


History 作为 全 局 路 由 服务 用 于 处 理 hashchange 事件 或 pushState > LACIE SAB > H fk 
发 回调 函数 。 我 们 不 需要 自己 去 做 这 些 事情 一 如 果 使 用 带 有 键 值 对 的 路 
由 ， Backbone.history 会 被 自动 创建 。 


Backbone 会 自动 判断 浏览 器 对 pushState 的 支持 ， 以 做 内 部 的 选择 。 不 支持 pushstate 的 
浏览 器 将 会 继续 使 用 基于 猫 点 的 URL 片段 ， 如 果 兼 容 pushstate 的 浏览 器 访问 了 某 个 URL 
猫 点 ， 将 会 被 透明 的 转换 为 真实 的 URL。 注意 使 用 丨 实 的 URLs 需要 web 服务 器 支持 直接 
泻 ZAIREN ? 因此 后 端 程序 也 需要 做 修改 o 例如， 如 果 有 这 样 一 个 路 由 /document/100 ， 
如 果 浏 览 器 直接 访问 它 ，Wweb 服务 器 必须 能 够 处 理 该 页 面 。 趋 于 对 搜索 引擎 疏 虫 的 兼容 ， 让 
服务 器 完全 为 该 页 面 生成 静态 HTML 是 非常 好 的 做 法 ... 但 是 如 果 要 做 的 是 一 个 web 应 用 ， 

只 需要 利用 Javascript 和 Backbone 视图 将 服务 器 返回 的 REST 数据 浑 娄 就 很 好 了 。 


start Backbone.history.start([options]) 当 所 有 的 Routers 创建 并 设置 完毕 ， 调 用 
Backbone.history.start() 开始 监控 hashchange 事件 并 分 配 路 由 。 后 续 调 

用 Backbone.history.start() 会 抛 出 一 个 错误 ， 并 且 Backbone.History.started 是 一 个 布尔 
值 ， 指 示 是 否 已 经 被 调用 。 


需要 指出 的 是 ， 如 果 想 在 应 用 中 使 用 HTML5 支持 的 pushstate ， 只 需要 这 样 
做 : Backbone.history.start({pushState : true}) ° 如 果 你 想 使 用 pushstate 的 话 ， 对 于 那 
些 本 身 不 支持 它 的 浏览 器 ， 需 要 用 整 页 刷新 代替 ， 您 可 以 添加 {hashChange: false} 到 选项 。 


如 果 应 用 不 是 基于 域名 的 根 路 径 / ， 需 要 告诉 History 基于 什么 路 径 : 


Backbone.history.start({pushState: true, root: "/public/search/"}) 


当 执 行 后 ， 如 果 某 个 路 由 成 功 匹 配 当 前 URL?’ Backbone.history.start() 返回 true ° 如 果 
没有 定义 的 路 由 匹配 当前 URL， 返 回 false 。 


如 果 服 务 器 已 经 演 染 了 整个 页 面 ， 但 又 不 希望 开始 History 时 触发 初始 路 由 ， 传 入 


silent : true PPT ° 


因为 在 Internet Explorer 中 基于 hash 的 历史 记录 依赖 于 &lt;iframeagt; ， 因 此 需要 确定 DOM 
已 准备 就 绪 后 再 调用 start() 。 


$(function(){ 

new WorkspaceRouter(); 

new HelpPaneRouter(); 

Backbone. history.start({pushState: true}); 
}); 


Backbone.sync ( 同步 ) 


Backbone.sync 是 Backbone 每 次 向 服务 器 读 取 或 保存 模型 时 都 要 调用 执行 的 函数 。 默认 情 
况 下 ， 它 使 用 jQuery.ajax 方法 发 送 RESTful json 请 求 ， 并 且 返 回 一 个 jqXHR 。 如 果 想 采 
用 不 同 的 持久 化 方案 ， 比 如 WebSockets, XML, 或 Local Storage， 我 们 可 以 重 载 该 函数 。 


Backbone.sync 的 语法 为 sync(method, model, [options]) ° 


e method- CRUD 方法 ( "create" , "read" , "update" , Or "delete" ) 
。 model— 要 被 保存 的 模型 (或 要 被 读 取 的 集合 ) 
e options 一 成 功 和 失败 的 回调 函数 ， 以 及 所 有 jQuery 请 求 支持 的 选项 


默认 情况 下 ， 当 Backbone.sync 发 送 请 求 以 保存 模型 时 ， 其 属性 会 被 序列 化 为 JSON， 并 以 
application/json 的 内 容 类 型 发 送 。 当 接 收 到 来 自 服务 器 的 JSON 响应 后 ， 对 经 过 服务 器 改 
变 的 模型 进行 拆 解 ， 然 后 在 客户 端 更 新 。 当 "read" 请 求 从 服务 器 端 响应 一 个 集合 
(Collection#fetch) 时 ， 便 拆 解 模型 属性 对 象 的 数组 。 


当 一 个 模型 或 集合 开始 sync 到 服务 器 时 ， 将 触发 一 个 "request" 事件 。 如 果 请 求 成 功 完 
成 你 会 得 到 一 个 "sync" 事件 ? 如 果 请 求 失败 ? 你 会 得 到 一 个 "error" 事件 © 


Sync 函数 可 重 写 为 全 局 性 的 Backbone. sync 9 或 在 细 粒 度 级 别 9 通过 添加 一 个 vine 函数 到 
Backbone 集 合 或 单个 模型 时 。 


默认 syne 映射 REST 风格 的 CRUD 类 似 下 面 这 样 : 


e create 一 POST /collection 

e read 一 GET /collection[/id] 

e update — PUT /collection/id 

e patch — PATCH /collection/id 
e delete — DELETE /collection/id 


举 个 例子 ， 一 个 Rail 4 处 理 程 序 响应 一 个 来 自 Backbone 的 "update" 调用 ， 可 能 是 这 样 的 : 
(在 真正 的 代码 中 ， 寺 万 不 要 育 目 的 使 用 update attributes ，， 你 可 以 被 改变 的 属性 始终 
是 白 名 单 。) 


def update 
account = Account.find params[:id] 
account.update_attributes params.require(:account).permit(:name, :otherparam) 
render :json => account 

end 


一 个 技巧 : 通过 设置 ActiveRecord: :Base.include_root_in_json = false ， 在 模型 上 禁用 默认 
命名 空间 的 to_json 来 整合 Rails 3.1 之 前 的 版 本 ，。 


ajax Backbone.ajax = function(request) { ... }; 如 果 你 想 使 用 自 定 义 的 AJAX 功 能 ， 或 者 你 
的 客户 端 不 支持 的 jQuery.ajax API， 你 需要 调整 的 东西 ， 您 可 以 通过 设置 Backbone.ajax 这 样 
做 。 


emulateHTTP Backbone.emulateHTTP = true 如 果 你 想 在 不 支持 Backbone 的 默认 REST/ 
HTTP 方 式 的 Web 服 务 器 上 工作 ， 您 可 以 选择 开局 Backbone.emulateHTTP ° 设置 该 选项 将 通 
过 post 方法 伪造 PUT > PATCH 和 DELETE 请 求 MA KAY A iA 

Æ X-HTTP-Method-override 头 信息 。 如 果 支 持 emulateJSON ， 此 时 该 请 求 会 向 服务 器 传 入 名 为 
_method 的 参数 。 


Backbone.emulateHTTP = true; 


model.save(); // POST to "/collection/id", with "_method=PUT" + header. 


emulateJSON Backbone.emulateJSON = true 如 果 你 想 在 不 支持 发 送 application/json 编码 
请 求 的 Web 服 务 器 上 工作 ， 设置 Backbone.emulateJSON = true; 将 导致 JSON 根 据 模 型 参数 进 
行 序列 化 ， 并 通过 application/x-www-form-urlencoded MIME 类 型 来 发 送 一 个 伪造 HTML 表 单 


Backbone.View (视图 ) 


Backbone 视图 几乎 约定 比 他 们 的 代码 多 一 他们 并 不 限定 你 的 HTML 或 CSS ， 并 可 以 配合 使 
用 任何 JavaScript 模 板 库 。 一 般 是 组 织 您 的 接口 转换 成 逻辑 视图 ， 通 过 模型 的 支持 ， 模 型 变 
化 时 ， 每 一 个 都 可 以 独立 地 进行 更 新 ， 而 不 必 重 新 绘制 该 页 面 。 我 们 再 也 不 必 钻 进 ISON 对 
象 中 ， 查 找 DOM 元 素 ， 手 动 更 新 HTML 了 ， 通 过 绑 定 视图 的 render 函数 到 模型 的 
"change" 事件 一 模型 数据 会 即时 的 显示 在 UL 中 。 

extend Backbone.View.extend(properties, [classProperties]) 开始 创建 自 定 义 的 视图 类 。 通 
常 我 们 需要 重 载 render 函数 ， 声 明 events ， 以 及 通过 tagName ，className ,或 id 为 视图 
指定 根 元 素 。 


var DocumentRow = Backbone.View.extend({ 
tagName: "li", 


className: "document-row", 


events: { 
"Click .icon": "open", 
"click .button.edit": "openEditDialog", 


"click .button.delete": "destroy" 
}, 


initialize: function() { 
this.listenTo(this.model, "change", this.render); 


}, 
render: function() { 
; ieee 

}); 


直到 运行 时 ， 像 tagName , id, className ， el, 和 events 这 样 的 属性 也 可 以 被 定义 为 一 
个 函数 ， 


constructor / initialize new view([options]) 有 几 个 特殊 的 选项 ， 如 果 传 入 ， 则 直接 注册 到 
视图 PH: model , collection , el , id , className , tagName , attributes 和 

events ° 如 果 视 图 定义 了 一 个 initialize 初 始 化 函数 ， 首 先 创 建 视图 时 ， 它 会 立刻 被 调用 。 
如 果 项 望 创建 一 个 指向 DOM 中 已 存在 的 元 素 的 视图 ， 传 入 该 元 素 作为 选 


项 : new View({el: existingElement}) ° 


var doc = documents. first(); 


new DocumentRow( { 
model: doc, 
id: "document-row-" + doc.id 


3); 


el view.el 所 有 的 视图 都 拥有 一 个 DOM 元 素 (el BIE) ， 即 使 该 元 素 仍 未 插入 页 面 中 去 。 
视图 可 以 在 任何 时 候 浑 染 ， 然 后 一 次 性 插入 DOM 中 去 ， 这 样 能 尽量 减少 reflows 和 repaints 
从 而 获得 高 性 能 的 Ul eo this.el 可 以 从 视图 的 tagname ，className ，id 和 
attributes 创建 ， 如 果 都 未 指定 ，el 会 是 一 个 空 div ° 


var ItemView = Backbone.View.extend({ 
tagName: 'li' 


3); 

var BodyView = Backbone. View. extend({ 
el: 'body' 

}); 

var item = new ItemView(); 

var body = new BodyView(); 

alert(item.el + ' ' + body.el); 


$el view.$el 一 个 视图 元 素 的 缓存 jQuery 对 象 。 一 个 简单 的 引用 ， 而 不 是 重新 包装 的 DOM 元 


view.$el.show(); 


listView.$el.append(itemView.el); 


setElement view.setElement(element) 如 果 你 想 应 用 一 个 Backbone 视 图 到 不 同 的 DOM 元 
素 ， 使 用 SetElement ， 这 也 将 创造 缓存 sel 引用 ， 视 图 的 委托 事件 从 旧 元 素 移动 到 新 元 素 
Es 


attributes view.attributes 属性 的 键 值 对 ， 将 被 设置 为 视图 el 上 的 HTML DOM 元 素 的 属 
性 ， 或 者 是 返回 这 样 的 键 值 对 的 一 个 函数 。 


$ (jQuery) view.$(selector) 如 果 页 面 中 引入 了 jQuery， 每 个 视图 都 将 拥有 $ BR TE 
视图 元 素 查询 作用 域内 运行 。 如 果 使 用 该 作用 域内 的 jQuery 函数 ， 就 不 需要 从 列表 中 指定 的 
元 素 获 取 模 型 的 ids 这 种 查询 了 ， 我 们 可 以 更 多 的 依赖 HTML class 属性 。 它 等 价 于 运 


行 : view.$el.find(selector) ° 


ui.Chapter = Backbone.View.extend({ 
serialize : function() { 
return { 
title: this.$(".title").text(), 
start: this.$(".start-page").text(), 
end: this.$(".end-page").text() 
J; 


3); 


template view.template([data]) 虽然 模板 化 的 视图 不 是 Backbone 直 接 提 供 的 一 个 功能 ， 它 
往往 是 一 个 在 你 视图 定义 template 函 数 很 好 的 约定 。 如 此 ， 浑 沫 你 的 视图 时 ， 您 方便 地 访 
问 实例 数据 。 例 如， 使 用 Underscore 的 模板 : 


var LibraryView = Backbone.View.extend({ 
template: _.template(...) 
}); 


render view.render() render 默认 实现 是 没有 操作 的 。 重 载 本 函数 可 以 实现 从 模型 数据 演 染 
视图 模板 ， 并 可 用 新 的 HTML 更 新 this.el ° 推荐 的 做 法 是 在 render 函数 的 末尾 
return this 以 开启 链 式 调用 5 


var Bookmark = Backbone.View.extend({ 
template: _.template(...), 
render: function() { 
this.$el.html(this.template(this.model.attributes) ); 
return this; 
} 
}); 


Backbone 并 不 知道 您 首选 HTML 模 板 的 方法 。 render CÈR) 函数 中 可 以 采用 拼接 HTML 字 
符 串 ”3 或 者 使 用 document.createElement 生成 DOM 树 。 但 还 是 建议 选择 一 个 好 的 
Javascript 模板 引擎 。 Mustache.js, Haml-js, 和 Eco 都 是 很 好 的 选择 。 因为 Underscore.js 已 
经 引入 页 面 了 ， 如 果 你 喜欢 简单 的 插入 JavaScript 的 样式 模板 。 .template 可 以 使 用 并 是 一 个 
很 好 的 选择 。 


无 论 基 于 什么 考虑 ， 都 永远 不 要 在 Javascript 中 拼接 HTML 字符 串 。 在 DocumentCloud 中 > 
我 们 使 用 Jammit 来 打包 JavaScript 模 板 ， 并 存储 在 /app/views 中 ， 作 为 我 们 主要 
的 core.js 包 的 一 部 分 。 


remove view.remove() 从 DOM 中 移 除 一 个 视图 。 同 事 调 用 stopListening 来 移 除 通过 
listenTo 绑 定 在 视图 上 的 所 有 事件 。 


delegateEvents delegateEvents([events]) 采用 jQuery 的 on 函数 来 为 视图 内 的 DOM 事件 
提供 回调 函数 声明 。 如 果 未 传 入 events 对 象 ， 使 用 this.events 作为 事件 源 。 事件 对 象 的 
书写 格式 为 {"event selector": "callback"} ° 省 略 selector 则 事件 被 绑 定 到 视图 的 根 元 
# ( this.el ) 。 默认 情况 下 ， delegateEvents 会 在 视图 的 构造 函数 内 被 调用 ， 因 此 如 果 有 
events 对 象 ， 所 有 的 DOM 事件 已 经 被 连接 ， 并 且 我 们 永远 不 需要 去 手动 调用 本 函数 。 
events 属性 也 可 以 被 定义 成 返回 events 对 象 的 函数 ， 这 样 让 我 们 定义 事件 ， 以 及 实现 事件 
的 继承 变 得 更 加 方便 。 

视图 render 期 间 使 用 delegateEvents 相 比 用 jQuery 向 子 元 素 绑 定 事件 有 更 多 优点 。 所 有 
注册 的 元 数 在 传递 给 jQuery 之 前 已 被 绑 定 到 视图 上 ， 因 此 当 回 调 防 数 执行 时 ， this 仍 将 指 
向 视图 对 象 。 4 delegateEvents 再 次 运行 ， 此 时 或 许 需 要 一 个 不 同 的 events 对 象 ， 所 以 
所 有 回调 函数 将 被 移 除 ， 然 后 重新 委托 一 这 对 模型 不 同行 为 也 不 同 的 视图 挺 有 用 处 。 


搜索 结果 页 面 显示 文档 的 视图 看 起 来 类 似 这 样 : 


var DocumentView = Backbone.View.extend({ 


events: { 
"dblclick" : "open", 
"click .icon.doc" : "select", 
"contextmenu .icon.doc" : "showMenu", 
"click .show_notes" : "toggleNotes", 
"click .title .lock" : "editAccessLevel", 
"mouseover .title .date" : "showTooltip" 

}, 


render: function() { 
this.$el.html(this.template(this.model.attributes) ); 
return this; 


}, 


open: function() { 
window.open(this.model.get("viewer_url")); 


}, 


select: function() { 
this.model.set({selected: true}); 


}, 


Hi; 


undelegateEvents undelegateEvents() 删除 视图 所 有 委托 事件 。 如 果 要 从 临时 的 DOM 中 禁 
用 或 删除 视图 时 ， 比 较 有 用 。 


Utility (实用 功能 ) 


Backbone.noConflict var backbone = Backbone.noConflict(); 返回 Backbone 对 象 的 原始 
值 。 您 可 以 使 用 Backbone.noConflict() 的 返回 值 以 保持 局 部 引用 Backbone。 通常 用 于 在 第 
三 方 网 站 上 引入 了 多 个 Backbone 文件 ， 避 免 冲突 。 


var localBackbone = Backbone.noConflict(); 
var model = localBackbone.Model.extend(...); 


Backbone.$ Backbone.$ = $， 如 果 页 面 上 有 多 个 jQuery 副本， 或 者 只 是 想 告 诉 Backbone 使 
用 特定 对 象 作为 其 DOM /Ajax 库 ， 那 么 这 个 属性 可 以 为 您 服务 。 如 果 您 正在 使 用 CommonJS 
加 载 Backbone (例如 ， 节 点 ， 组 件 ， 或 browserify) 您 必须 手动 设置 该 属性 。 


var Backbone.$ = require('jquery'); 


F.A.Q. 


Why use Backbone, not [other framework X]? If your eye hasn't already been caught by 


the adaptability and elan on display in the above list of examples, we can get more specific: 


Backbone.js aims to provide the common foundation that data-rich web applications with 


ambitious interfaces require — while very deliberately avoiding painting you into a corner by 


making any decisions that you're better equipped to make yourself. 


The focus is on supplying you with helpful methods to manipulate and query your data, 
not on HTML widgets or reinventing the JavaScript object model. 

Backbone does not force you to use a single template engine. Views can bind to HTML 
constructed in your favorite way. 

It's smaller. There are fewer kilobytes for your browser or phone to download, and less 
conceptual surface area. You can read and understand the source in an afternoon. 

It doesn't depend on stuffing application logic into your HTML. There's no embedded 
JavaScript, template logic, or binding hookup code in data- or ng- attributes, and no 
need to invent your own HTML tags. 

Synchronous events are used as the fundamental building block, not a difficult-to- 
reason-about run loop, or by constantly polling and traversing your data structures to 
hunt for changes. And if you want a specific event to be asynchronous and aggregated, 
no problem. 

Backbone scales well, from embedded widgets to massive apps. 

Backbone is a library, not a framework, and plays well with others. You can embed 
Backbone widgets in Dojo apps without trouble, or use Backbone models as the data 
backing for D3 visualizations (to pick two entirely random examples). 

"Two-way data-binding" is avoided. While it certainly makes for a nifty demo, and works 
for the most basic CRUD, it doesn't tend to be terribly useful in your real-world app. 
Sometimes you want to update on every keypress, sometimes on blur, sometimes when 
the panel is closed, and sometimes when the "save" button is clicked. In almost all 
cases, simply serializing the form to JSON is faster and easier. All that aside, if your 
heart is set, go for it. 

There's no built-in performance penalty for choosing to structure your code with 
Backbone. And if you do want to optimize further, thin models and templates with 
flexible granularity make it easy to squeeze every last drop of potential performance out 
of, say, IE8. 


There's More Than One Way To Do It It's common for folks just getting started to treat the 


examples listed on this page as some sort of gospel truth. In fact, Backbone.js is intended to 


be fairly agnostic about many common patterns in client-side code. For example... 


References between Models and Views can be handled several ways. Some people like 
to have direct pointers, where views correspond 1:1 with models ( model.view and 

view.model ). Others prefer to have intermediate "controller" objects that orchestrate the 
creation and organization of views into a hierarchy. Others still prefer the evented approach, 
and always fire events instead of calling methods directly. All of these styles work well. 


Batch operations on Models are common, but often best handled differently depending on 
your server-side setup. Some folks don't mind making individual Ajax requests. Others 
create explicit resources for RESTful batch operations: /notes/batch/destroy?ids=1,2,3,4 . 
Others tunnel REST over JSON, with the creation of "changeset" requests: 


"create": [array of models to create] 
"update": [array of models to update] 
"destroy": [array of model ids to destroy] 


} 


Feel free to define your own events. Backbone.Events is designed so that you can mix it 
in to any JavaScript object or prototype. Since you can use any string as an event, it's often 


handy to bind and trigger your own custom events: model.on("selected:true") Or 
model.on("editing") 


Render the UI as you see fit. Backbone is agnostic as to whether you use Underscore 
templates, Mustache.js, direct DOM manipulation, server-side rendered snippets of HTML, 
or jQuery Ulin your render function. Sometimes you'll create a view for each model ... 
sometimes you'll have a view that renders thousands of models at once, in a tight loop. Both 
can be appropriate in the same app, depending on the quantity of data involved, and the 
complexity of the UI. 


Nested Models & Collections It's common to nest collections inside of models with 

Backbone. For example, consider a Mailbox model that contains many Message models. 

One nice pattern for handling this is have a this.messages collection for each mailbox, 

enabling the lazy-loading of messages, when the mailbox is first opened ... perhaps with 
MessageList views listening for "add" and "remove" events. 


var Mailbox = Backbone.Model.extend({ 


initialize: function() { 
this.messages = new Messages; 
this.messages.url = '/mailbox/' + this.id + '/messages'; 
this.messages.on("reset", this.updateCounts); 


F 


}); 
var inbox = new Mailbox; 
// And then, when the Inbox is opened: 


inbox.messages.fetch({reset: true}); 


If you're looking for something more opinionated, there are a number of Backbone plugins 
that add sophisticated associations among models, available on the wiki. 


Backbone doesn't include direct support for nested models and collections or "has many" 
associations because there are a number of good patterns for modeling structured data on 
the client side, and Backbone should provide the foundation for implementing any of them. 
You may want to... 


e Mirror an SQL database's structure, or the structure of a NoSQL database. 

e Use models with arrays of "foreign key" ids, and join to top level collections (a-la tables). 

e For associations that are numerous, use a range of ids instead of an explicit list. 

e Avoid ids, and use direct references, creating a partial object graph representing your 
data set. 

e Lazily load joined models from the server, or lazily deserialize nested models from 
JSON documents. 


Loading Bootstrapped Models When your app first loads, it's common to have a set of 
initial models that you know you're going to need, in order to render the page. Instead of 
firing an extra AJAX request to fetch them, a nicer pattern is to have their data already 
bootstrapped into the page. You can then use reset to populate your collections with the 
initial data. At DocumentCloud, in the ERB template for the workspace, we do something 
along these lines: 


<script> 

var accounts = new Backbone.Collection; 

accounts.reset(<%= @accounts.to_json %>); 

var projects = new Backbone.Collection; 

projects.reset(<%= @projects.to_json(:collaborators => true) %>); 
</script> 


You have to escape alt;/ within the JSON string, to prevent javascript injection attacks. 


Extending Backbone Many JavaScript libraries are meant to be insular and self-enclosed, 
where you interact with them by calling their public API, but never peek inside at the guts. 
Backbone.js is not that kind of library. 


Because it serves as a foundation for your application, you're meant to extend and enhance 
it in the ways you see fit — the entire source code is annotated to make this easier for you. 
You'll find that there's very little there apart from core functions, and most of those can be 
overridden or augmented should you find the need. If you catch yourself adding methods to 

Backbone.Model.prototype , or creating your own base subclass, don't worry — that's how 
things are supposed to work. 


How does Backbone relate to "traditional" MVC? Different implementations of the Model- 
View-Controller pattern tend to disagree about the definition of a controller. If it helps any, in 
Backbone, the View class can also be thought of as a kind of controller, dispatching events 
that originate from the UI, with the HTML template serving as the true view. We call it a View 
because it represents a logical chunk of UI, responsible for the contents of a single DOM 
element. 


Comparing the overall structure of Backbone to a server-side MVC framework like Rails, the 
pieces line up like so: 


e Backbone.Model - Like a Rails model minus the class methods. Wraps a row of data 
in business logic. 

e Backbone.Collection — A group of models on the client-side, with 
sorting/filtering/aggregation logic. 

e Backbone.Router — Rails routes.rb + Rails controller actions. Maps URLs to 
functions. 

e Backbone.View — A logical, re-usable piece of UI. Often, but not always, associated 
with a model. 

e Client-side Templates — Rails .html.erb views, rendering a chunk of HTML. 


Binding "this" Perhaps the single most common JavaScript "gotcha" is the fact that when 
you pass a function as a callback, its value for this is lost. When dealing with events and 
callbacks in Backbone, you'll often find it useful to rely on listenTo or the optional context 
argument that many of Underscore and Backbone's methods use to specify the this that 
will be used when the callback is later invoked. (See .each, .map, and object.on, to name 
a few). View events are automatically bound to the view's context for you. You may also find 
it helpful to use _.bind and .bindAll from Underscore.js. 


var MessageList = Backbone.View.extend({ 


initialize: function() { 
var messages = this.collection; 
messages.on("reset", this.render, this); 
messages.on("add", this.addMessage, this); 
messages.on("remove", this.removeMessage, this); 


messsages.each(this.addMessage, this); 


} 
}); 
// Later, in the app... 


Inbox.messages.add(newMessage) ; 


Working with Rails Backbone.js was originally extracted from a Rails application; getting 
your client-side (Backbone) Models to sync correctly with your server-side (Rails) Models is 
painless, but there are still a few things to be aware of. 


By default, Rails versions prior to 3.1 add an extra layer of wrapping around the JSON 
representation of models. You can disable this wrapping by setting: 


ActiveRecord: :Base.include_root_in_json = false 


... In your configuration. Otherwise, override parse to pull model attributes out of the 
wrapper. Similarly, Backbone PUTs and POSTs direct JSON representations of models, 
where by default Rails expects namespaced attributes. You can have your controllers filter 
attributes directly from params , or you can override toJSON in Backbone to add the extra 
wrapping Rails expects. 


Examples 


The list of examples that follows, while long, is not exhaustive. If you've worked on an app 
that uses Backbone, please add it to the wiki page of Backbone apps. 


Jerome Gravel-Niquet has contributed a Todo List application that is bundled in the 
repository as Backbone example. If you're wondering where to get started with Backbone in 
general, take a moment to read through the annotated source. The app uses a LocalStorage 
adapter to transparently save all of your todos within your browser, instead of sending them 
to a server. Jérôme also has a version hosted at localtodos.com. 


DocumentCloud 


The DocumentCloud workspace is built on Backbone.js, with Documents, Projects, Notes, 
and Accounts all as Backbone models and collections. If you're interested in history — both 
Underscore.js and Backbone.js were originally extracted from the DocumentCloud 
codebase, and packaged into standalone JS libraries. 


USA Today 


USA Today takes advantage of the modularity of Backbone's data/model lifecycle — which 
makes it simple to create, inherit, isolate, and link application objects — to keep the 
codebase both manageable and efficient. The new website also makes heavy use of the 
Backbone Router to control the page for both pushState-capable and legacy browsers. 
Finally, the team took advantage of Backbone's Event module to create a PubSub API that 
allows third parties and analytics packages to hook into the heart of the app. 


Rdio 


New Rdio was developed from the ground up with a component based framework based on 
Backbone.js. Every component on the screen is dynamically loaded and rendered, with data 
provided by the Rdio API. When changes are pushed, every component can update itself 
without reloading the page or interrupting the user's music. All of this relies on Backbone's 
views and models, and all URL routing is handled by Backbone's Router. When data 
changes are signaled in realtime, Backbone's Events notify the interested components in the 
data changes. Backbone forms the core of the new, dynamic, realtime Rdio web and 
desktop applications. 


Hulu 


Hulu used Backbone.js to build its next generation online video experience. With Backbone 
as a foundation, the web interface was rewritten from scratch so that all page content can be 
loaded dynamically with smooth transitions as you navigate. Backbone makes it easy to 
move through the app quickly without the reloading of scripts and embedded videos, while 
also offering models and collections for additional data manipulation support. 


Quartz 


Quartz sees itself as a digitally native news outlet for the new global economy. Because 
Quartz believes in the future of open, cross-platform web applications, they selected 
Backbone and Underscore to fetch, sort, store, and display content from a custom 
WordPress API. Although qz.com uses responsive design for phone, tablet, and desktop 
browsers, it also takes advantage of Backbone events and views to render device-specific 
templates in some cases. 


Earth 


Earth.nullschool.net displays real-time weather conditions on an interactive animated globe, 
and Backbone provides the foundation upon which all of the site's components are built. 
Despite the presence of several other javascript libraries, Backbone's non-opinionated 
design made it effortless to mix-in the Events functionality used for distributing state changes 
throughout the page. When the decision was made to switch to Backbone, large blocks of 
custom logic simply disappeared. 


Vox 


Vox Media, the publisher of SB Nation, The Verge, Polygon, Eater, Racked, Curbed, and 
Vox.com, uses Backbone throughout Chorus, its home-grown publishing platform. Backbone 
powers the liveblogging platform and commenting system used across all Vox Media 
properties; Coverage, an internal editorial coordination tool; SB Nation Live, a live event 
coverage and chat tool; and Vox Cards, Vox.com's highlighter-and-index-card inspired app 
for providing context about the news. 


Gawker Media 


Kinja is Gawker Media's publishing platform designed to create great stories by breaking 
down the lines between the traditional roles of content creators and consumers. Everyone — 
editors, readers, marketers — have access to the same tools to engage in passionate 
discussion and pursue the truth of the story. Sharing, recommending, and following within 
the Kinja ecosystem allows for improved information discovery across all the sites. 


Kinja is the platform behind Gawker, Gizmodo, Lifehacker, io9 and other Gawker Media 
blogs. Backbone.js underlies the front-end application code that powers everything from 
user authentication to post authoring, commenting, and even serving ads. The JavaScript 
stack includes Underscore.js and jQuery, with some plugins, all loaded with RequireJS. 
Closure templates are shared between the Play! Framework based Scala application and 
Backbone views, and the responsive layout is done with the Foundation framework using 
SASS. 


Flow 


MetaLab used Backbone.js to create Flow, a task management app for teams. The 
workspace relies on Backbone.js to construct task views, activities, accounts, folders, 
projects, and tags. You can see the internals under window.Flow . 


Gilt Groupe 


Gilt Groupe uses Backbone.js to build multiple applications across their family of sites. Gilt's 
mobile website uses Backbone and Zepto.js to create a blazing-fast shopping experience for 
users on-the-go, while Gilt Live combines Backbone with WebSockets to display the items 
that customers are buying in real-time. Gilt's search functionality also uses Backbone to filter 
and sort products efficiently by moving those actions to the client-side. 


Enigma 


Enigma is a portal amassing the largest collection of public data produced by governments, 
universities, companies, and organizations. Enigma uses Backbone Models and Collections 
to represent complex data structures; and Backbone's Router gives Enigma users unique 
URLs for application states, allowing them to navigate quickly through the site while 
maintaining the ability to bookmark pages and navigate forward and backward through their 
session. 


NewsBlur 


NewsBlur is an RSS feed reader and social news network with a fast and responsive UI that 
feels like a native desktop app. Backbone.js was selected for a major rewrite and transition 
from spaghetti code because of its powerful yet simple feature set, easy integration, and 
large community. If you want to poke around under the hood, NewsBlur is also entirely open- 
source. 


WordPress.com 


WordPress.com is the software-as-a-service version of WordPress. It uses Backbone.js 
Models, Collections, and Views in its Notifications system. Backbone.js was selected 
because it was easy to fit into the structure of the application, not the other way around. 
Automattic (the company behind WordPress.com) is integrating Backbone.js into the Stats 
tab and other features throughout the homepage. 


Foursquare 


Foursquare is a fun little startup that helps you meet up with friends, discover new places, 
and save money. Backbone Models are heavily used in the core JavaScript API layer and 
Views power many popular features like the homepage map and lists. 


Bitbucket 


Bitbucket is a free source code hosting service for Git and Mercurial. Through its models and 
collections, Backbone.js has proved valuable in supporting Bitbucket's REST API, as well as 
newer components such as in-line code comments and approvals for pull requests. 
Mustache templates provide server and client-side rendering, while a custom Google 
Closure inspired life-cycle for widgets allows Bitbucket to decorate existing DOM trees and 
insert new ones. 


Disqus 


Disqus chose Backbone.js to power the latest version of their commenting widget. 
Backbone’s small footprint and easy extensibility made it the right choice for Disqus’ 
distributed web application, which is hosted entirely inside an iframe and served on 
thousands of large web properties, including IGN, Wired, CNN, MLB, and more. 


Delicious 


Delicious is a social bookmarking platform making it easy to save, sort, and store bookmarks 
from across the web. Delicious uses Chaplin.js, Backbone.js and AppCache to build a full- 
featured MVC web app. The use of Backbone helped the website and mobile apps share a 
single API service, and the reuse of the model tier made it significantly easier to share code 
during the recent Delicious redesign. 
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Khan Academy is on a mission to provide a free world-class education to anyone anywhere. 
With thousands of videos, hundreds of JavaScript-driven exercises, and big plans for the 
future, Khan Academy uses Backbone to keep frontend code modular and organized. User 
profiles and goal setting are implemented with Backbone, jQuery and Handlebars, and most 


new feature work is being pushed to the client side, greatly increasing the quality of the API. 
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IRCCloud 


|RCCloud is an always-connected IRC client that you use in your browser — often leaving it 
open all day in a tab. The sleek web interface communicates with an Erlang backend via 
websockets and the |RCCloud API. It makes heavy use of Backbone.js events, models, 
views and routing to keep your IRC conversations flowing in real time. 
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Pitchfork 





Pitchfork uses Backbone.js to power its site-wide audio player, Pitchfork.tv, location routing, 


a write-thru page fragment cache, and more. Backbone.js (and Underscore.js) helps the 
team create clean and modular components, move very quickly, and focus on the site, not 


the spaghetti. 
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Spin 


Spin pulls in the latest news stories from their internal API onto their site using Backbone 
models and collections, and a custom sync method. Because the music should never stop 
playing, even as you click through to different "pages", Spin uses a Backbone router for 
navigation within the site. 
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ZocDoc helps patients find local, in-network doctors and dentists, see their real-time 


availability, and instantly book appointments. On the public side, the webapp uses 


Backbone.js to handle client-side state and rendering in search pages and doctor profiles. In 
addition, the new version of the doctor-facing part of the website is a large single-page 
application that benefits from Backbone's structure and modularity. ZocDoc's Backbone 
classes are tested with Jasmine, and delivered to the end user with Cassette. 
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Walmart Mobile 


Walmart used Backbone.js to create the new version of their mobile web application and 
created two new frameworks in the process. Thorax provides mixins, inheritable events, as 
well as model and collection view bindings that integrate directly with Handlebars templates. 
Lumbar allows the application to be split into modules which can be loaded on demand, and 
creates platform specific builds for the portions of the web application that are embedded in 
Walmart's native Android and iOS applications. 
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Groupon Now! 


Groupon Now! helps you find local deals that you can buy and use right now. When first 
developing the product, the team decided it would be AJAX heavy with smooth transitions 
between sections instead of full refreshes, but still needed to be fully linkable and shareable. 
Despite never having used Backbone before, the learning curve was incredibly quick — a 
prototype was hacked out in an afternoon, and the team was able to ship the product in two 
weeks. Because the source is minimal and understandable, it was easy to add several 
Backbone extensions for Groupon Now!: changing the router to handle URLs with 
querystring parameters, and adding a simple in-memory store for caching repeated requests 
for the same data. 
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Basecamp 


37Signals chose Backbone.js to create the calendar feature of its popular project 
management software Basecamp. The Basecamp Calendar uses Backbone.js models and 
views in conjunction with the Eco templating system to present a polished, highly interactive 
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Slavery Footprint 


Slavery Footprint allows consumers to visualize how their consumption habits are connected 
to modern-day slavery and provides them with an opportunity to have a deeper conversation 
with the companies that manufacture the goods they purchased. Based in Oakland, 
California, the Slavery Footprint team works to engage individuals, groups, and businesses 
to build awareness for and create deployable action against forced labor, human trafficking, 
and modern-day slavery through online tools, as well as off-line community education and 
mobilization programs. 
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Stripe provides an API for accepting credit cards on the web. Stripe's management interface 


was recently rewritten from scratch in CoffeeScript using Backbone.js as the primary 


framework, Eco for templates, Sass for stylesheets, and Stitch to package everything 


together as CommonJS modules. The new app uses Stripe's API directly for the majority of 


its actions; Backbone.js models made it simple to map client-side models to their 


corresponding RESTful resources. 
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Airbnb 


Airbnb uses Backbone in many of its products. It started with Airbnb Mobile Web (built in six 


weeks by a team of three) and has since grown to Wish Lists, Match, Search, Communities, 


Payments, and Internal Tools. 
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SoundCloud Mobile 


SoundCloud is the leading sound sharing platform on the internet, and Backbone.js provides 
the foundation for SoundCloud Mobile. The project uses the public SoundCloud AP! as a 
data source (channeled through a nginx proxy), jQuery templates for the rendering, Qunit 
and PhantomJS for the testing suite. The JS code, templates and CSS are built for the 
production deployment with various Node.js tools like ready.js, Jake, jsdom. The 
Backbone.History was modified to support the HTML5 history.pushsState . 
Backbone.sync was extended with an additional SessionStorage based cache layer. 
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Art.sy 


Art.sy is a place to discover art you'll love. Art.sy is built on Rails, using Grape to serve a 
robust JSON API. The main site is a single page app written in CoffeeScript and uses 
Backbone to provide structure around this API. An admin panel and partner CMS have also 
been extracted into their own API-consuming Backbone projects. 


Pandora 


When Pandora redesigned their site in HTMLS, they chose Backbone.js to help manage the 
user interface and interactions. For example, there's a model that represents the "currently 
playing track", and multiple views that automatically update when the current track changes. 
The station list is a collection, so that when stations are added or changed, the UI stays up 
to date. 


Inkling 


Inkling is a cross-platform way to publish interactive learning content. Inkling for Web uses 
Backbone.js to make hundreds of complex books — from student textbooks to travel guides 
and programming manuals — engaging and accessible on the web. Inkling supports 
WebGL-enabled 3D graphics, interactive assessments, social sharing, and a system for 
running practice code right in the book, all within a single page Backbone-driven app. Early 
on, the team decided to keep the site lightweight by using only Backbone.js and raw 
JavaScript. The result? Complete source code weighing in at a mere 350kb with feature- 
parity across the iPad, iPhone and web clients. Give it a try with this excerpt from 
JavaScript: The Definitive Guide. 


Code School 


Code School courses teach people about various programming topics like CoffeeScript, 
CSS, Ruby on Rails, and more. The new Code School course challenge page is built from 
the ground up on Backbone.js, using everything it has to offer: the router, collections, 
models, and complex event handling. Before, the page was a mess of jQuery DOM 
manipulation and manual Ajax calls. Backbone.js helped introduce a new way to think about 
developing an organized front-end application in JavaScript. 


CloudApp 


CloudApp is simple file and link sharing for the Mac. Backbone.js powers the web tools 
which consume the documented API to manage Drops. Data is either pulled manually or 
pushed by Pusher and fed to Mustache templates for rendering. Check out the annotated 
source code to see the magic. 
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SeatGeek 


SeatGeek's stadium ticket maps were originally developed with Prototype.js. Moving to 
Backbone.js and jQuery helped organize a lot of the UI code, and the increased structure 
has made adding features a lot easier. SeatGeek is also in the process of building a mobile 
interface that will be Backbone.js from top to bottom. 
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Easel 


Easel is an in-browser, high fidelity web design tool that integrates with your design and 
development process. The Easel team uses CoffeeScript, Underscore.js and Backbone.js 
for their rich visual editor as well as other management functions throughout the site. The 
structure of Backbone allowed the team to break the complex problem of building a visual 
editor into manageable components and still move quickly. 
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Jolicloud 


Jolicloud is an open and independent platform and operating system that provides music 
playback, video streaming, photo browsing and document editing — transforming low cost 
computers into beautiful cloud devices. The new Jolicloud HTML5 app was built from the 
ground up using Backbone and talks to the Jolicloud Platform, which is based on Node.js. 
Jolicloud works offline using the HTML5 AppCache, extends Backbone.sync to store data in 
IndexedDB or localStorage, and communicates with the Joli OS via WebSockets. 
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Salon.io 


Salon.io provides a space where photographers, artists and designers freely arrange their 
visual art on virtual walls. Salon.io runs on Rails, but does not use much of the traditional 
stack, as the entire frontend is designed as a single page web app, using Backbone.js, 
Brunch and CoffeeScript. 
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Our fellow Knight Foundation News Challenge winners, MapBox, created an open-source 
map design studio with Backbone.js: TileMill. TileMill lets you manage map layers based on 
shapefiles and rasters, and edit their appearance directly in the browser with the Carto 
styling language. Note that the gorgeous MapBox homepage is also a Backbone.js app. 


Blossom 


Blossom is a lightweight project management tool for lean teams. Backbone.js is heavily 
used in combination with CoffeeScript to provide a smooth interaction experience. The app 
is packaged with Brunch. The RESTful backend is built with Flask on Google App Engine. 
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Trello 


Trello is a collaboration tool that organizes your projects into boards. A Trello board holds 
many lists of cards, which can contain checklists, files and conversations, and may be voted 
on and organized with labels. Updates on the board happen in real time. The site was built 
ground up using Backbone.js for all the models, views, and routes. 
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Activity 
Trello attached Taco.png to 
You can attach pictures 
and files... 
Jul 20, 2012 at 9:42 am 


Trello added Want current 
tips, usage examples, or 
API info? to Advanced. 

Apr 25, 2012 at 8:57 am 


Trello added Need help? to 
Advanced. 
Jan 9, 2012 at 2:33 pm 


Trello added Want updates 
on new features? to 
Advanced. 

Jan 9, 2012 at 2:31 pm 


Trello added Want to use 
keyboard shortcuts? We 
have them! to Advanced. 
Jan 9, 2012 at 2:24 pm 


Trello added Use as many 
boards as you want. We'll 
make more! to Done. 
Sep 9, 2011 at 5:14 pm 


[FT] Trello added To learn more 


Cristi Balan and Irina Dumitrascu created Tzigla, a collaborative drawing application where 
artists make tiles that connect to each other to create surreal drawings. Backbone models 


help organize the code, routers provide bookmarkable deep links, and the views are 


rendered with haml.js and Zepto. Tzigla is written in Ruby (Rails) on the backend, and 


CoffeeScript on the frontend, with Jammit prepackaging the static assets. 


Examples 


人 日 日 quack, quack, pixel duck - a collaborative drawing on Tzigla 
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materials are not mandatory, but are always a nice 
touch. 
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Change Log 


1.1.2 一 Feb. 20, 2014 — Diff 一 Docs 


e Backbone no longer tries to require jQuery in Node/CommonJS environments, for better 
compatibility with folks using Browserify. If you'd like to have Backbone use jQuery from 
Node, assign it like So: Backbone.$ = require('jquery'); 

e Bugfix for route parameters with newlines in them. 


1.1.1 一 Feb. 13, 2014 — Diff — Docs 


e Backbone now registers itself for AMD (Require.js), Bower and Component, as well as 
being a CommonJS module and a regular (Java)Script. Whew. 

e Added an execute hook to the Router, which allows you to hook in and custom-parse 
route arguments, like query strings, for example. 

e Performance fine-tuning for Backbone Events. 

e Better matching for Unicode in routes, in old browsers. 

e Backbone Routers now handle query params in route fragments, passing them into the 
handler as the last argument. Routes specified as strings should no longer include the 
query string ( 'foo?:query' should be 'foo' ). 


1.1.0 — Oct. 10, 2013 — Diff — Docs 


e Made the return values of Collection's set , add, remove , and reset more useful. 
Instead of returning this , they now return the changed (added, removed or updated) 
model or list of models. 

e Backbone Views no longer automatically attach options passed to the constructor as 

this.options and Backbone Models no longer attach url and urlRoot options, but 
you can do it yourself if you prefer. 

e All "invalid" events now pass consistent arguments. First the model in question, then 
the error object, then options. 

e You are no longer permitted to change the id of your model during parse . Use 

idAttribute instead. 

e On the other hand, parse is now an excellent place to extract and vivify incoming 
nested JSON into associated submodels. 

e Many tweaks, optimizations and bugfixes relating to Backbone 1.0, including URL 
overrides, mutation of options, bulk ordering, trailing slashes, edge-case listener leaks, 
nested model parsing... 


1.0.0 — March 20, 2013 — Diff — Docs 


e Renamed Collection's "update" to set, for parallelism with the similar model.set() , and 


contrast with reset. It's now the default updating mechanism after a fetch. If you'd like to 
continue using "reset", pass {reset: true} . 
Your route handlers will now receive their URL parameters pre-decoded. 
Added listenToOnce as the analogue of once. 
Added the findWhere method to Collections, similar to where. 
Added the keys , values , pairs , invert , pick ,and omit Underscore.js methods 
to Backbone Models. 
The routes in a Routers route map may now be function literals, instead of references 
to methods, if you like. 

url and urlRoot properties may now be passed as options when instantiating a new 
Model. 


0.9.10 — Jan. 15, 2013 — Diff — Docs 


A "route" event is triggered on the router in addition to being fired on 
Backbone.history . 
Model validation is now only enforced by default in mModel#save and no longer enforced 
by default upon construction or in Model#set , unless the {validate:true} option is 
passed. 
View#make has been removed. You'll need to use $ directly to construct DOM 
elements now. 
Passing {silent:true} on change will no longer delay individual "change:attr" 
events, instead they are silenced entirely. 
The Model#change method has been removed, as delayed attribute changes are no 
longer available. 
Bug fix on change where attribute comparison uses !== instead of _.isEqual . 
Bug fix where an empty response from the server on save would not call the success 
function. 
parse Now receives options as its second argument. 
Model validation now fires invalid event instead of error . 


0.9.9 — Dec. 13, 2012 — Diff — Docs 


Added listenTo and stopListening to Events. They can be used as inversion-of-control 
flavors of on and off , for convenient unbinding of all events an object is currently 
listening to. view.remove() automatically calls view.stopListening() . 

When using add on a collection, passing {merge: true} will now cause duplicate 
models to have their attributes merged in to the existing models, instead of being 
ignored. 

Added update (which is also available as an option to fetch ) for "smart" updating of 
sets of models. 

HTTP PATCH support in save by passing {patch: true} . 


The Backbone object now extends Events so that you can use it as a global event bus, 

if you like. 

Added a "request" event to Backbone.sync, which triggers whenever a request begins 

to be made to the server. The natural complement to the "sync" event. 

Router URLs now support optional parts via parentheses, without having to use a regex. 

Backbone events now supports once , similar to Node's once , or jQuery's one . 

Backbone events now support jQuery-style event maps obj.on({click: action}) . 

While listening toa reset event, the list of previous models is now available in 
options.previousModels , for convenience. 

Validation now occurs even during "silent" changes. This change means that the 
isValid method has been removed. Failed validations also trigger an error, even if an 

error callback is specified in the options. 

Consolidated "sync" and "error" events within Backbone.sync. They are now 

triggered regardless of the existence of success or error callbacks. 

For mixed-mode APIs, Backbone.sync now accepts emulateHTTP and emulateJSON aS 

inline options. 

Collections now also proxy Underscore method name aliases (collect, inject, foldl, foldr, 

head, tail, take, and so on...) 

Removed getBycid from Collections. collection.get now supports lookup by both 
id and cid. 

After fetching a model or a collection, all defined parse functions will now be run. So 

fetching a collection and getting back new models could cause both the collection to 

parse the list, and then each model to be parsed in turn, if you have both functions 
defined. 

Bugfix for normalizing leading and trailing slashes in the Router definitions. Their 

presence (or absence) should not affect behavior. 

When declaring a View, options , el , tagName , id and className may now be 

defined as functions, if you want their values to be determined at runtime. 

Added a Backbone.ajax hook for more convenient overriding of the default use of 
$.ajax . If AJAX is too passé, set it to your preferred method for server communication. 
Collection#sort nowtriggersa sort event, instead ofa reset event. 

Calling destroy ona Model will now return false ifthe model isNew . 

To set what library Backbone uses for DOM manipulation and Ajax calls, use 
Backbone.$ = ... instead of setDomLibrary . 

Removed the Backbone.wrapError helper method. Overriding sync should work better 

for those particular use cases. 

To improve the performance of add , options.index will no longer be set in the add 

event callback. collection.indexOf(model) can be used to retrieve the index of a model 

as necessary. 

For semantic and cross browser reasons, routes will now ignore search parameters. 


Routes like search?query=..&page=3 Should become search/../3 . 
e Model#set no longer accepts another model as an argument. This leads to subtle 
problems and is easily replaced with model.set(other.attributes) . 


0.9.2 — March 21, 2012 — Diff — Docs 


e Instead of throwing an error when adding duplicate models to a collection, Backbone 
will now silently skip them instead. 

e Added push, pop, unshift, and shift to collections. 

e A model's changed hash is now exposed for easy reading of the changed attribute 
delta, since the model's last "change" event. 

e Added where to collections for simple filtering. 

e You can now use a single off call to remove all callbacks bound to a specific object. 

e Bug fixes for nested individual change events, some of which may be "silent". 

e Bug fixes for URL encoding in location.hash fragments. 

e Bug fix for client-side validation in advance of a save call with {wait: true}. 

e Updated / refreshed the example Todo List app. 


0.9.1 — Feb. 2, 2012 — Diff — Docs 


e Reverted to 0.5.3-esque behavior for validating models. Silent changes no longer trigger 
validation (making it easier to work with forms). Added an isvalid function that you 
can use to check if a model is currently in a valid state. 

e |f you have multiple versions of jQuery on the page, you can now tell Backbone which 
one to use with Backbone.setDomLibrary . 

e Fixes regressions in 0.9.0 for routing with "root", saving with both "wait" and "validate", 
and the order of nested "change" events. 


0.9.0 — Jan. 30, 2012 一 Diff — Docs 


e Creating and destroying models with create and destroy are now optimistic by 
default. Pass {wait: true} as an option if you'd like them to wait for a successful 
server response to proceed. 

e Two new properties on views: $el — a cached jQuery (or Zepto) reference to the 
view's element, and setElement , which should be used instead of manually setting a 
view's el . It will both set view.el and view.$el correctly, as well as re-delegating 
events on the new DOM element. 

e You can now bind and trigger multiple spaced-delimited events at once. For example: 

model.on("change:name change:age", ...) 

e When you don't know the key in advance, you may now call model.set(key, value) as 
well as save. 

e Multiple models with the same id are no longer allowed in a single collection. 

e Addeda "sync" event, which triggers whenever a model's state has been successfully 


synced with the server (create, save, destroy). 

e bind and unbind have been renamed to on and off for clarity, following jQuery's 
lead. The old names are also still supported. 

e A Backbone collection's comparator function may now behave either like a sortBy 
(pass a function that takes a single argument), or like a sort (pass a comparator function 
that expects two arguments). The comparator function is also now bound by default to 
the collection — so you can refer to this within it. 

e Aview's events hash may now also contain direct function values as well as the string 
names of existing view methods. 

e Validation has gotten an overhaul — a model's validate function will now be run even 
for silent changes, and you can no longer create a model in an initially invalid state. 

e Added shuffle and initial to collections, proxied from Underscore. 

e Model#urlRoot may now be defined as a function as well as a value. 

e vView#attributes may now be defined as a function as well as a value. 

e Calling fetch on a collection will now cause all fetched JSON to be run through the 
collection's model's parse function, if one is defined. 

e You may now tell a router to navigate(fragment, {replace: true}) , which will either use 

history.replaceState Or location.hash.replace ,in order to change the URL without 
adding a history entry. 

e Within acollection's add and remove events, the index of the model being added or 
removed is now available as options.index . 

e Added an undelegateEvents to views, allowing you to manually remove all configured 
event delegations. 

e Although you shouldn't be writing your routes with them in any case — leading slashes 
( / ) are now stripped from routes. 

e Calling clone on a model now only passes the attributes for duplication, not a 
reference to the model itself. 

e Calling clear on a model now removes the id attribute. 


0.5.3 — August 9, 2011 — Diff — Docs A View's events property may now be defined as a 
function, as well as an object literal, making it easier to programmatically define and inherit 
events. groupBy is now proxied from Underscore as a method on Collections. If the server 
has already rendered everything on page load, pass 

Backbone. history.start({silent: true}) to prevent the initial route from triggering. Bugfix 
for pushState with encoded URLs. 


0.5.2 — July 26, 2011 — Diff — Docs The bind function, can now take an optional third 
argument, to specify the this of the callback function. Multiple models with the same id 
are now allowed in a collection. Fixed a bug where calling .fetch(jQueryOptions) could 
cause an incorrect URL to be serialized. Fixed a brief extra route fire before redirect, when 
degrading from pushState . 


0.5.1 — July 5, 2011 — Diff — Docs Cleanups from the 0.5.0 release, to wit: improved 
transparent upgrades from hash-based URLs to pushState, and vice-versa. Fixed 
inconsistency with non-modified attributes being passed to Model#initialize . Reverted a 
0.5.0 change that would strip leading hashbangs from routes. Added contains as an alias 
for includes . 


0.5.0 — July 1, 2011 — Diff — Docs Alarge number of tiny tweaks and micro bugfixes, best 
viewed by looking at the commit diff. HTML5 pushstate support, enabled by opting-in with: 

Backbone. history.start({pushState: true}) . Controller Was renamed to Router , for 
Clarity. Collection#refresh was renamed to cCollection#reset to emphasize its ability to 
both reset the collection with new models, as well as empty out the collection when used 
with no parameters. saveLocation was replaced with navigate . RESTful persistence 
methods (save, fetch, etc.) now return the jQuery deferred object for further success/error 
chaining and general convenience. Improved XSS escaping for model#escape . Added a 

urlRoot option to allow specifying RESTful urls without the use of a collection. An error is 
thrown if Backbone.history.start is called multiple times. collection#create now validates 
before initializing the new model. view.el can now be a jQuery string lookup. Backbone 
Views can now also take an attributes parameter. Model#defaults can now be a function 
as well as a literal attributes object. 


0.3.3 — Dec 1, 2010 — Diff — Docs Backbone.js now supports Zepto, alongside jQuery, as 
a framework for DOM manipulation and Ajax support. Implemented Model#escape, to 
efficiently handle attributes intended for HTML interpolation. When trying to persist a model, 
failed requests will now trigger an "error" event. The ubiquitous options argument is now 
passed as the final argument to all "change" events. 


0.3.2 — Nov 23, 2010 — Diff — Docs Bugfix for IE7 + iframe-based "hashchange" events. 
sync may now be overridden on a per-model, or per-collection basis. Fixed recursion error 
when calling save with no changed attributes, within a "change" event. 


0.3.1 — Nov 15, 2010 — Diff — Docs All "add" and "remove" events are now sent 
through the model, so that views can listen for them without having to know about the 
collection. Added a remove method to Backbone.View. toJjson is no longer called at all for 

'read' and 'delete' requests. Backbone routes are now able to load empty URL 
fragments. 


0.3.0 — Nov 9, 2010 — Diff — Docs Backbone now has Controllers and History, for doing 
client-side routing based on URL fragments. Added emulateHTTP to provide support for 
legacy servers that don't do put and DELETE . Added emulateJson for servers that can't 
accept application/json encoded requests. Added Model#clear, which removes all 
attributes from a model. All Backbone classes may now be seamlessly inherited by 
CoffeeScript classes. 


0.2.0 — Oct 25, 2010 — Diff — Docs Instead of requiring server responses to be 
namespaced under a model key, now you can define your own parse method to convert 
responses into attributes for Models and Collections. The old handleEvents function is now 
named delegateEvents, and is automatically called as part of the View's constructor. Added 
a toJSON function to Collections. Added Underscore's chain to Collections. 


0.1.2 — Oct 19, 2010 — Diff — Docs Added a Model#fetch method for refreshing the 
attributes of single model from the server. An error callback may now be passed to set 
and save as an option, which will be invoked if validation fails, overriding the "error" 
event. You can now tell backbone to use the _method hack instead of HTTP methods by 
setting Backbone.emulateHTTP = true . Existing Model and Collection data is no longer sent 
up unnecessarily with GET and DELETE requests. Added a rake lint task. Backbone is 
now published as an NPM module. 


0.1.1 — Oct 14, 2010 — Diff — Docs Added a convention for initialize functions to be 
called upon instance construction, if defined. Documentation tweaks. 


0.1.0 — Oct 13, 2010 — Docs Initial Backbone release. 


